fuiwanted

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds significant behavioral details: return format (per-model score, confidence, signals, raw_response + combined view), default model (free Workers AI Llama-3.3-70b), API key requirement for Anthropic, and cost responsibility ('you pay Anthropic directly'). 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 four sentences, front-loaded with purpose, then details, then use cases. It is efficient with no redundant phrases, though a minor reduction could be possible.

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

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

The tool has 4 parameters, no output schema, and annotations covering safety. The description explains the return format, distinguishes free vs paid model usage, and provides use cases. For a read-only, idempotent probing tool, this is complete enough for an AI agent to understand invocation and selection.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: default model details, that _apiKey is only needed for Anthropic, and that context helps disambiguate entities. It also clarifies that the models parameter can be omitted for just workers-ai.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs for what they know about a business / brand / product / topic') and clearly distinguishes this tool from siblings by mentioning AI-marketing audits, pre-launch brand checks, and competitive monitoring. It uniquely addresses visibility scoring 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 explicitly states when to use the tool (for AI-marketing audits, pre-launch brand checks, competitive monitoring) and provides context on default vs paid models. However, it does not compare to sibling tools like scan_competitor_ai_presence or mention when not to use it.

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

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

The description adds behavioral context beyond annotations by explaining it routes to 4,774 tools, returns structured answers with citation URIs, and works on every tier in one fast call. Annotations already indicate read-only, idempotent, non-destructive behavior; description complements this well.

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 front-loaded with the key preference statement. It efficiently combines purpose, usage guidelines, examples, and sibling differentiation. Every sentence serves a purpose, though minor redundancy could be trimmed. Overall well-structured.

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 broad scope (access to thousands of sources) and no output schema, the description fully covers return format, routing behavior, and fallback tools. It explains the tool's role as a default entry point and provides enough context for an agent to decide when to use it.

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

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

The input schema has 100% coverage with descriptions for all 6 parameters (including aliases). The description adds natural language examples and context about the type of questions, but the baseline score of 3 is appropriate since the schema already fulfills the core parameter documentation.

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 routes factual queries to a large set of verified sources and returns structured citations. It lists many domain examples and explicitly positions itself as the default entry point, contrasting with siblings like ask_pipeworx_grounded and deep_research.

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 when-to-use guidance (prefer over web search for factual questions), concrete examples, and when-not-to-use instructions (e.g., for hallucination-resistant answers use the grounded variant, for broad questions use deep_research). It also specifies that it automatically routes to news for breaking topics.

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, etc. Description adds detailed process, return structure (answer, evidence, confidence, source, refusal_reason), failure modes, and cost of extra LLM call. No contradictions.

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

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

Front-loaded with key purpose; structured with process, returns, and usage guidelines. Slightly verbose with some redundancy (e.g., repeated sibling mention), 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 complexity (4,774 tools, 1,242 sources, high-stakes use), description fully covers return values, failure modes, and behavioral caveats. No output schema, so description compensates completely.

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

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

Schema coverage is 100% with aliases for question. Description adds context that the parameter is a natural language question used for routing, but does not provide additional constraints or format details 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?

Clearly states 'Hallucination-resistant answer mode for high-stakes reads.' Identifies verb 'ask' and resource 'Pipeworx Grounded.' Distinguishes from sibling 'ask_pipeworx' by noting cost 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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups.' 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?

The description extensively discloses behavioral traits beyond annotations, including fan-out mechanisms per category, response shapes, confidence levels, parent event extraction, news fallback, safety short-circuits for low confidence and closed markets, wide-spread tradeability warnings, and resolution-rule risk. This far exceeds what annotations provide.

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 long and densely detailed, which reduces conciseness. However, it is well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and the main purpose is front-loaded. The length is justified by the tool's complexity, but it could be 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 (3 parameters, no output schema, many edge cases), the description is exceptionally complete. It covers inputs, process, outputs, error states, fallback behaviors, and resolution rules, compensating fully for the lack of an output schema.

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

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

The description adds significant meaning beyond the input schema by explaining the market parameter accepts slug, URL, or question text, the depth parameter defines quick vs. thorough fan-out, and include_raw warns about response size and use cases. Schema coverage is 100%, but these details enhance agent understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input (market slug, URL, or question text) and distinguishes itself from sibling tools like polymarket_edges by focusing on comprehensive research rather than just price 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 explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear usage context. It does not explicitly exclude alternatives but is sufficient for the agent to decide when to invoke.

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

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

The description goes beyond annotations to reveal important behavioral traits: data source (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. Annotations already indicate readOnly and idempotent, which are consistent.

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 concise, using bullet-style examples and clear sections. Every sentence adds value, though it could be slightly tighter without losing clarity for the 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 fully covers the tool's capabilities: comparison scope, data per entity type, result sorting, and format. Despite lacking an output schema, it adequately informs the agent of the response structure (paired data + citation URIs).

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 descriptive parameter names. The description adds meaning by explaining what data each 'type' retrieves and providing examples for 'values.' It adds context about sorting and data freshness that the schema does not capture.

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 ('Compare') and resource ('entities'), specifies the action as side-by-side comparison of 2-5 companies or drugs, and provides concrete query examples. It distinguishes itself from sequential single-pack lookups, which is a sibling approach.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also describes what data is pulled for each type (company vs drug), helping the agent decide when to use this tool versus alternatives.

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

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

Beyond annotations (readOnly, idempotent, destructiveHint), the description adds essential context: account required, paid plan for thorough, not open-web search, returns findings packet with gaps, and expected latency (15-60s). 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?

Despite length, every sentence contributes critical information: prerequisites, use cases, alternatives, behavior, output format, and limitations. Front-loaded with account requirement. 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?

Fully covers prerequisites, input behavior, parallel decomposition, output structure (findings packet with citations and gaps), failure mode (empty gaps for uncataloged topics), and timing. No output schema needed given detailed return description.

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: question is clarified as natural language accepting broad/multi-part queries, and depth enum is explained with facet counts and plan restrictions. This adds meaning beyond the schema 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 performs multi-source research across structured data sources, contrasting with sibling tools like ask_pipeworx for single lookups or current news. It specifies a specific verb and resource, 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 provides when to use (broad/multi-part questions over structured data) and when not to use (single lookup, current news), with alternative tools named. Also includes account prerequisites and paid plan requirement 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 readOnlyHint, idempotentHint, destructiveHint. Description adds that results are 'ready to call directly, no second schema lookup needed' and includes curated examples. 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?

Well-structured with front-loaded purpose, followed by domain examples, then output description. Each sentence adds value, but could be slightly more concise without losing clarity.

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

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

Despite no output schema, description fully explains what is returned (top-N tools with names, descriptions, schemas, examples). Also mentions limit default and max. 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% with descriptions for all 6 parameters. Description adds meaning by explaining that 'query' accepts multiple aliases and giving concrete examples. Reinforces how to use the parameters effectively.

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 discovers tools by describing the data or task, lists specific domains (SEC filings, FDA drugs, etc.), and explains output (top-N tools with schemas). It differentiates from siblings by positioning itself as a first-step 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?

Explicitly says 'Call this FIRST when you have many tools available' and 'Use when you need to browse, search, look up, or discover what tools exist'. Provides clear context for when to use, though could more explicitly state 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details on data sources (SEC, XBRL, USPTO, news, GLEIF), return fields (cik, filings, fundamentals, patents, news, LEI), and USPTO API sunset behavior. 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?

Single dense paragraph; front-loaded with examples. Could be more structured (e.g., bullet points for return fields), but remains focused and not overly long.

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 major aspects: purpose, inputs, return fields, limitations. For a tool without output schema, it adequately explains return values. Some details on structure (e.g., how fundamentals are sorted) are implied but not explicit.

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 100%. Description adds meaning: 'type' only supports 'company', 'value' can be ticker or zero-padded CIK, names not supported. Provides examples and clarifies use of resolve_entity for names.

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

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

Description clearly states tool provides a full cross-source profile of a US public company, using verbs like 'tell me about', 'research', 'brief me on'. It distinguishes itself from chaining single-pack lookups and sibling tools like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies input requirements: ticker or CIK, not names, and references resolve_entity as alternative.

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 destructive and idempotent. Description adds context about clearing sensitive data and staleness, reinforcing the destructive nature 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 front-loaded purpose and usage. Every sentence adds value; 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 one-parameter destructive tool with strong annotations, the description adequately covers purpose, usage, and complements. No output schema needed.

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 description 'Memory key to delete'. The tool description adds no extra parameter 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?

Clearly states verb 'Delete' and resource 'memory by key'. Distinguishes from siblings by explicitly pairing with 'remember' and 'recall'.

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 clear use cases: stale context, task completion, clearing sensitive data. Mentions complementary tools but lacks explicit '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 adds behavioral details beyond annotations: it fetches the page, extracts title/description/key links, and emits standard markdown. This complements the readOnlyHint, openWorldHint, and idempotentHint 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, efficient paragraph with front-loaded purpose and no wasted words. 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 fully explains what the tool does and its output (single text blob). However, it lacks comparison to similar sibling tools like ai_visibility_check, which might also deal with AI indexing. Given no output schema, the 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 description coverage is 100% and already documents both parameters well. The description adds minimal extra meaning beyond the schema (e.g., tying max_links to 'link entries'), so baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the resource (llms.txt file) and action (generate). It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file creation.

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

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

The description provides explicit use cases (e.g., getting client site indexed, drafting for own project), but does not explicitly state when not to use it or compare directly to sibling tools. It implies usage context but lacks exclusions.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it returns specific fields and by default lists active subscriptions, offering useful 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 concise sentences: first declares function and return fields, second provides usage context. No wasted words, front-loaded with 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 simple list tool with annotations and schema coverage, the description covers purpose, return fields, and usage context. No output schema needed; fields are listed. Paired with siblings, it 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%, so the description carries less burden. The description mentions 'active' implying default behavior, but the schema already describes the parameter. No additional detail on parameter semantics 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 action ('List') and the resource ('subscriptions'), specifies it returns active subscriptions, and lists the fields. This distinguishes it from siblings 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?

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use guidance. It does not explicitly state when not to use, but the context implies it is for review.

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, but the description adds critical behavioral context: rate-limited to 5 per identifier per day, does not count against tool-call quota, free, and the team reads digests daily. This goes well beyond annotations.

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

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

The description is front-loaded with purpose, followed by usage scenarios, then constraints and tips. Every sentence earns its place, no fluff, and it's appropriately sized 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 3 parameters (one enum, one nested object), no output schema, the description fully covers purpose, usage, parameter semantics, constraints, and processing. Nothing essential is missing.

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

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

Schema coverage is 100% with each parameter described. The description enriches the 'type' enum with detailed explanations, clarifies context fields with examples, and specifies message limits. Adds significant 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?

The description clearly states the tool's purpose: submitting feedback (broken, missing, or praise) to the Pipeworx team. It distinguishes itself from siblings by being the only feedback tool, with examples of when to use it.

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 each type (bug, feature, data_gap, praise) and provides a negative guideline: don't paste the end-user's prompt. It also mentions rate limits and quota implications.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds valuable details: self-aggregating from CF analytics, no PII, cached 5min-1h.

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 a bullet list, front-loaded with purpose, every sentence adds value. No redundant or vague phrasing.

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 one parameter, no output schema, and rich annotations, the description fully covers data source, privacy, caching, and use cases. Nothing missing.

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

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

Single parameter fully documented in schema and description adds context beyond enum values: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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 returns top tools, packs, and call volume over a window. Distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending aggregate data.

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

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

Provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and aligning use case. Lacks explicit when-not-to-use guidance 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: monotonicity checks, partition_sum, Jaccard similarity filter, placeholder filter, fill check with book depth. It warns about false signals when realizable edge is ≤ 0. 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 dense and relatively long, but every sentence adds value and it is well-structured with clear sections for modes, parameters, algorithms, and output. A slightly more concise phrasing could be used, but it's justified by the tool's complexity.

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

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

Despite no output schema, the description fully explains the response structure, including fields like gap_pp, suggested_trade, partition_check details, and fill check. It covers edge cases and references sibling tool for custom sizing. Highly complete.

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

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

Schema already has 100% coverage with descriptions for both parameters. Description adds deeper semantics: event accepts slugs or URLs, topic is a seed question, and explains the different behaviors and algorithms for each mode.

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 it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes itself from siblings by specifying the specific algorithms and modes, and mentions related tools like polymarket_fill_risk for custom sizing.

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

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

Explicitly explains when to call with no args (trending_scan), with 'event' (single-event mode), or with 'topic' (cross-event mode). Recommends 'event' for specific markets and explains that cross-event mode catches patterns missed by single-event. 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 goes well beyond the annotations by detailing the algorithms behind each segment (e.g., 'crypto_price (lognormal barrier from 90d FRED log-returns)'), the response structure ('by_segment', '_diagnostics'), and the caching behavior ('Cached 1h at the KV level keyed on all knobs'). This fully discloses the tool's behavior and internal logic, with no contradiction to the provided 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 extremely detailed and well-structured, front-loading the main purpose and key segments. However, it is overly verbose, including extensive algorithmic details (e.g., 'per-sport α (tennis 1.02, soccer 1.10...)') that could be summarized or omitted without losing core meaning. A more concise version would improve Clarity for quick AI parsing.

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 comprehensively specifies the response structure, including top-level fields (by_segment, fed_candidates, _diagnostics) and the format of each opportunity (edge_pp_net, kelly_fraction, market details, 24h-move warning). It also explains the caching, parameter knobs, and filtering logic, making the tool's behavior completely understandable without additional documentation.

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

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

The input schema already provides descriptions for all 9 parameters (100% coverage), so the baseline is 3. The description adds significant value by explaining the logic behind the parameters (e.g., 'Tradeable-edge filter' for min_liquidity and max_spread_pp, and how min_partition_leg_kelly works for partitions). This enriches the agent's 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and scope (disagreement with Pipeworx data). It distinguishes itself from sibling tools by detailing the unique edge categories (model-driven, structural arbitrage, concentrated longshot) and the 'Built for what should I bet on today' use case.

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

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

The description provides context on when to use this tool: for discovering betting opportunities in Polymarket without paging hundreds of markets. It explains the three segments and the tradeable-edge knobs, implicitly guiding usage. However, it does not explicitly compare itself to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, nor does it state when not to use it, which would earn a 5.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds detailed behavioral context: it uses daily snapshots, computes trend and decay, explains limits like 60-day TTL, and clarifies decay is based on daily closes, not intraday. 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 dense and front-loaded with purpose. It provides a clear structure separating purpose, response format, and limits. Though long, every sentence adds value. Could be slightly more concise, but overall well-organized.

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 response format, including all fields and their meanings. It covers parameters, behavior, and limits, making it complete for an agent to understand the tool's capabilities and constraints.

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

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

Schema covers 100% of parameters with descriptions. The description elaborates on default values, clamping behavior, and provides a detailed explanation of the response structure (tracked, expired, snapshot_dates) that 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's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question and distinguishes itself from sibling tools like polymarket_edges (which likely shows current edges) and polymarket_arbitrage (different scope).

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

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

The description implies when to use this tool (to compare fresh vs old edges) and why it matters. However, it does not explicitly list when not to use it or mention alternatives. The context is clear but lacks explicit exclusion criteria.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: walks the ladder, returns top_of_book/vwap/slippage/verdict, and for basket mode explains per-leg fill detail and forced directional 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 somewhat long but well-structured with clear sections for single-market and basket modes. Each sentence adds value, though some details could be condensed. Still, it maintains clarity without unnecessary 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 complexity (two modes, multiple output fields, risk analysis) and no output schema, the description comprehensively covers parameters, behaviors, return values, and usage context. It explains risks of partial fills and directional exposure, ensuring the agent understands the tool's full implications.

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 meaning beyond the schema. It explains mutual exclusivity of market vs event, differential interpretation of size_usd (max spend on buys vs target proceeds on sells in single-market, settlement notional in basket), and default side behavior in basket mode (auto from partition sum).

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 defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinguishes two modes (single-market and basket) with explicit descriptions of each, making it easy for the agent to select the correct mode based on context.

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

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

Provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the consequences of not using it (partial basket fills convert arb into unhedged directional position), effectively telling when to use and why.

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, openWorldHint, idempotentHint, destructiveHint), the description details the tool's behavior: it returns raw probabilities, spreads, compatibility warnings, temporal alignment, and skipped cross-type/subtype counters. It explains safety fields and conditions for meaningful spreads. 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 a clear opening summary, mode explanations, response format, safety fields, and a caution. Each sentence adds value, and the most critical information is front-loaded. 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, the description fully explains the return values (leg-by-leg prices, spreads, safety fields) and covers edge cases with compatibility warnings. It is thorough and provides all necessary context for an AI agent to use the tool effectively.

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

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

With 100% schema coverage, baseline is 3. The description adds significant value by explaining the two modes, providing examples of topic values, and clarifying how explicit tickers override. It warns about pre-mapped topic limitations, which 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's purpose as cross-venue spread comparison between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on two different venues. The two modes (topic shortcuts and explicit pairings) are clearly explained.

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 (comparing spreads across venues) and includes warnings about pre-mapped topics often being non-tradeable. It implicitly contrasts with siblings but does not explicitly recommend alternative tools for when this tool is inappropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds behavioral details: listing all keys when key omitted, scoping to identifier, relationship to save/delete. Adds value 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?

Three sentences, each serving a clear purpose: core action, usage context, scoping and pairing. No unnecessary words, front-loaded with the primary function.

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, good annotations, and no output schema, the description fully explains behavior in all cases, scoping, and relationships to siblings.

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 the single key parameter with a description. The tool description adds context about omitting the key to list all keys and scoping, 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?

Description clearly states the tool retrieves a value saved via remember or lists all keys if key is omitted. It explicitly distinguishes from sibling tools remember and forget by naming them.

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

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

Describes when to use the tool: to look up stored context without re-deriving. Mentions scoping and pairing with remember/forget. Does not explicitly state when not to use, but context is sufficient.

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

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

The description includes a mutation behavior (mark_read:true flags events as read), which contradicts the annotation readOnlyHint=true. This is a critical inconsistency, so despite other useful context (polling safe, alternative access), transparency is severely compromised.

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

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

The description is concise (4 sentences), front-loaded with the core purpose, and each sentence adds distinct information (return fields, filters, side effects, alternatives). 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?

Covers purpose, return fields, filtering options, side effect (mark_read), and alternative access method. Without an output schema, the description adequately explains return values. Minor omission: default limit not stated, but overall sufficiently complete for a 5-parameter optional tool.

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

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

Schema coverage is 100%, and the description adds examples (e.g., type filter 'sec_8k') and explains the effect of mark_read. However, it does not cover all parameters (e.g., limit, unread_only not mentioned), so it adds moderate value 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?

Description starts with 'Pull fired events from your subscription feed,' specifying a clear verb ('pull') and resource ('fired events from subscription feed'). It also details return fields (source, citation_uri, raw payload), which distinguishes it from siblings like recent_changes.

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

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

The description clearly indicates use for retrieving recent alerts from the subscription feed and mentions polling and an alternative HTTP endpoint. However, it does not explicitly state when to avoid this tool or compare it directly 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds fallback behavior (GDELT to GNews), specific error handling (USPTO soft-fail), return structure (changes[] grouped by source, total_changes, citation URIs), and rate information, providing comprehensive behavioral details.

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 informative but somewhat verbose (multiple example queries and sentences). It front-loads the core purpose effectively, but could be more concise by trimming redundant example phrases.

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

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

Given no output schema, the description adequately explains the return format (changes[], total_changes, citation URIs), covers fallback behavior, error handling, and source details, making it fully self-contained 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?

With 100% schema coverage, the description still adds value by clarifying relative shorthand meanings, example values, and use of '30d' or '1m' for typical monitoring, which goes beyond the schema descriptions.

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

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

The description clearly states it provides a change feed for a company in a time window, listing specific sources (SEC, GDELT/GNews, USPTO) and explicitly distinguishes from sibling entity_profile (static profile), making the purpose unambiguous and differentiated.

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 example queries and explicitly directs to use entity_profile for static profile queries. However, it does not explicitly state when not to use this tool (e.g., for non-temporal needs), though the guidance is clear for typical 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 provide idempotentHint=true and destructiveHint=false, but the description adds valuable behavioral context: scoping by identifier, persistence duration (persistent vs. 24h), and implied safe overwrite (supports idempotency). 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?

Every sentence earns its place: starts with the core action, then usage criteria, then behavioral details. No filler, well-structured for quick parsing.

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 covers what happens, scoping, persistence, and how to complement with recall/forget. Complete for an agent to understand the tool's full lifecycle.

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

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

Schema covers both parameters with descriptions, but the tool description adds practical guidance on key naming conventions (e.g., 'subject_property') and what values can contain. This goes beyond the schema, earning a 4.

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

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

The description uses a specific verb-resource pair ('Save data ... key-value pair') and explicitly distinguishes from sibling tools recall and forget. It clearly states what the tool does and how it differs from alternatives.

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

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

The description explicitly tells when to use the tool ('when you discover something worth carrying forward'), provides context for different session types (authenticated vs. anonymous), and pairs with recall/forget for retrieval/deletion. No guesswork needed.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by description detailing cascading internal lookups and exact return fields per type (ticker, CIK, URI for company; RxCUI, ingredient, brand for drug). 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?

Front-loaded with examples, then general description, then detailed type breakdown. Slightly long but each 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?

No output schema, but description explains return values in detail for each type, including citation URIs. Also mentions cascading behavior. Completes the picture for a 2-parameter 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 provides descriptions for both parameters. Description adds value by explaining the accepted inputs for 'value' (ticker, CIK, name for company; brand/generic for drug) and clarifies the 'type' enum values 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?

Starts with concrete examples and clearly states it resolves a name to a canonical identifier. Distinguishes from siblings by noting it replaces multiple manual lookups.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides supported types and what each returns, guiding when to use. No explicit exclusions 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 indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds that it probes each entity, ranks results, and returns metrics (score, confidence, signal density). This provides useful behavioral context beyond annotations alone.

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

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

Two sentences, front-loaded with the core purpose. Every sentence adds value: first states what it does, second gives usage context and expected output. 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?

No output schema exists, but description mentions return format (ranked list with score, confidence, signal density). It also notes entity count constraints (2-8). However, it lacks details on error handling, rate limits, or 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 has 100% parameter description coverage. The description adds meaning by explaining that the first entry is treated as 'subject' and the rest as competitors, and clarifies the role of optional parameters like models and _apiKey.

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 compares AI visibility across multiple entities using ai_visibility_check, ranks by score, and identifies most/least recognized. It explicitly distinguishes from the sibling ai_visibility_check by being a composite multi-entity 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 provides a concrete use case ('competitive AI-marketing audits') and an illustrative question. It implicitly suggests when to use this tool over single-entity probes, but does not explicitly state when not to use it or list alternatives.

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

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

The description discloses behavioral traits beyond annotations: it is a composite read operation, fans out to external sources, returns specific fields, and includes details about partial failures (bundlephobia first measurement can take 5-30s, sources_failed will list timeouts). Annotations already indicate read-only and idempotent, and description adds 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 concise and front-loaded with the core purpose. It packs significant detail in a single paragraph without excessive verbosity, though it could be broken into shorter sentences for easier scanning.

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 (composite check, multiple sources, partial failures), the description is remarkably complete. It covers input, output fields, limitations, ecosystem scope, and failure behavior. Without an output schema, it effectively describes the return structure and 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 has 100% coverage with descriptions for both parameters (package name and version). Description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted for the package parameter and that version defaults to latest when omitted. This goes beyond the schema's bare 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 as a composite check for adding npm packages, specifying the data sources (deps.dev and bundlephobia) and the types of questions it answers (safety, popularity, size). It distinguishes itself from sibling tools by focusing on npm packages and aggregating multiple aspects into one call.

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 (e.g., agent asks 'is X safe / popular / small' or 'what does adding lodash cost me') and provides guidance on limitations: NPM ecosystem only in v1, with other ecosystems to be queried via deps.dev directly. It also mentions graceful degradation on partial failures.

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. Description adds significant behavioral context: truncation at 200K chars, BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, returns character offsets and similarity scores. 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?

Three sentences packed with essential information, front-loaded with core purpose, efficient 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?

Given the tool's complexity (semantic search, embedding model, offset returns), the description covers all key aspects. No output schema but description mentions return values (passages with offsets and scores).

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 parameter descriptions. Description adds examples for query, explains text as document text, and notes default limit and max chars. 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?

The description clearly states it performs semantic search inside a fetched record, specifying the verb 'search' and resource 'record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the use case of reducing context.

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 record is too large for prompt) and mentions pairing with another tool. Does not explicitly list when not to use, but context is clear enough 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 indicate mutability (readOnlyHint=false) and idempotence (idempotentHint=true). The description enriches this with detailed behavioral traits: authentication needs, delivery channel specifics (SMS cap, webhook auto-disable), and type-specific filtering examples. 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 appropriately concise despite its length. It is front-loaded with the core purpose, then organizes details by subscription types and delivery channels. Every sentence adds functional value without redundancy.

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

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

Given no output schema, the description mentions the return of subscription ID but omits error conditions or response structure. It covers most behavioral aspects but could be more complete regarding failure 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%, and the description adds significant meaning beyond the schema. It includes concrete examples for each subscription type (e.g., sec_8k with item codes) and elaborates on delivery channel objects (SMS verification, webhook signing secret).

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by its create action.

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

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

The description specifies usage requirements (Pipeworx OAuth account) and constraints (anonymous/BYO cannot persist). It lacks explicit guidance on when not to use or comparisons with siblings like recent_alerts, but overall provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the return format (category-bucketed examples with tool shapes) and that it draws from a live catalog, but does not reveal critical new behavioral traits beyond what annotations and schema provide.

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 trigger phrases and well-structured, but slightly verbose. It could be more concise while maintaining clarity, but each sentence contributes meaning.

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

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

Given the tool's role as an onboarding entry point with no output schema, the description fully explains its purpose, usage, argument behavior, and return content. It is complete for an agent to decide when to invoke it.

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 one optional parameter. The description adds meaning by listing example values for 'topic' (e.g., 'finance', 'pharma') and specifying that omitting the argument returns a full cross-category spread, which goes beyond the schema's generic 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 tool is the onboarding entry point for new agents, returning category-bucketed example questions. It uses specific verb-resource pairs like 'return category-bucketed example questions' and distinguishes itself from siblings like 'ask_pipeworx' and '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?

Explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with/without the 'topic' argument. This provides clear context and alternatives.

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

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

Disclosures beyond annotations: row deactivated (not deleted), historical events remain. Annotations already indicate non-destructive mutation, but description adds precise behavioral context.

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

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

Two concise sentences with no redundancy. Front-loaded action and method, followed by key behavioral 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?

Complete for a simple one-param tool with annotations. Covers purpose, constraint, side effect, and ties to sibling tool for historical data.

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 description of id. Description adds little beyond schema ('by id' and association with subscribe). 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?

Clear verb 'Cancel' and resource 'subscription'. Distinguishes from siblings like subscribe and list_subscriptions by mentioning deactivation and linking to recent_alerts for historical events.

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 ownership constraint ('only cancel your own subscriptions') and directs historical data to recent_alerts, but lacks explicit when-not-to-use or comparison 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: returns a verdict with specific categories, extracted structured form, actual value with citation, and percent delta. No contradictions.

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

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

The description is front-loaded with trigger phrases and a clear purpose statement. While it is somewhat lengthy, every sentence adds value – explaining scope, domain, return values, and why it replaces multiple calls. 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?

Given the tool has only one parameter, no output schema, and rich annotations, the description fully covers the tool's behavior, return types, and use cases. It is complete for its complexity.

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

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

The input schema has 100% description coverage for the single required 'claim' parameter. The description adds value by specifying the domain of claims supported (company-financial) and providing examples of valid claims, enhancing the schema's minimal 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 tool's purpose: verifying natural-language factual claims, specifically company-financial claims against authoritative sources. It provides trigger phrases and explicitly distinguishes it from sibling tools by noting it replaces multiple sequential calls.

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.' It also specifies the domain (US public company financial claims via SEC EDGAR + XBRL) and mentions it replaces 4-6 sequential calls, guiding when to use it over alternatives.

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