Seo Keywords Ads

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

The annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds key behavioral details: default model (Workers AI Llama-3.3-70b, free), optional Anthropic probing (BYO key), and return structure (per-model score, confidence, signals, raw_response + combined view). This aligns with and enriches the 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 paragraph of four sentences, front-loaded with the main action and output, followed by optional parameter details and use cases. Every sentence adds necessary information without 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 has 4 parameters (1 required), no output schema, and comprehensive annotations, the description fully covers what the agent needs to know: what it does, how to use optional parameters, what the output looks like (per-model and combined), and typical use cases. No gaps remain.

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

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

Schema description coverage is 100% (all four parameters have descriptions in the schema). The description adds meaningful context beyond the schema: it clarifies that 'workers-ai' is the free default, that _apiKey is needed only for Anthropic, and that the context parameter helps disambiguate. This provides value beyond the baseline of 3.

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

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

The description starts with a specific verb-resource pair ('Probe one or more LLMs for what they know about a business/brand/product/topic') and clearly states the output type ('score visibility (0-100) per model'). It distinguishes from siblings by mentioning AI-marketing audits and competitive monitoring, which are unique use cases not covered by similar sibling tools like 'scan_competitor_ai_presence'.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the optional parameters (models, _apiKey, context) and their implications (free vs BYO key). It does not explicitly list when not to use, but the context provided is sufficient for most agents.

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. Description adds useful behavioral context: routes to 4,482 tools, returns structured answers with citation URIs, works on every tier, one fast 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?

The description is relatively long but well-structured with bold key points, clear examples, and comparisons. Front-loads the most important guidance (prefer over web search). Every sentence earns its place without redundancy.

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

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

Given the complexity (many sources, no output schema), annotations and description together provide sufficient context. The description covers routing, citation, performance characteristics, and fallback options. A minor gap: no explicit mention of rate limits or authentication, but annotations imply safe read.

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% (all parameters described). Description mentions aliases and provides examples, but the schema already defines parameters fully. Baseline 3 is appropriate as description adds minimal extra semantic 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?

The description clearly states the tool is for answering factual questions about current/historical data across many domains (SEC, FDA, etc.) using a specific verb 'ask' and resource 'Pipeworx'. It distinguishes from 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?

Explicitly states 'PREFER OVER WEB SEARCH' and provides concrete when-to-use scenarios with examples. Also clarifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions).

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 set readOnly, openWorld, idempotent, and destructive hints. The description adds crucial behavioral details: costs an extra LLM call, returns structured response with evidence and refusal reasons, and picks the right tool from many. 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 concise with about 5 sentences, front-loading the purpose. Every sentence adds value: explanation of routing, extraction process, response structure, use cases, and cost trade-off. 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?

Given the tool's complexity (routing, extraction, refusal modes), the description is thorough. It explains costs, response fields, failure reasons, and appropriate use cases. No output schema exists, but the description compensates well.

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 6 aliases for question. The description notes 'Your question in natural language' and that aliases are accepted, but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' that returns only facts from tool results with explicit refusals. It distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and use case for citations and acting on answers.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples like financial verdicts, legal claims, and medical lookups. It also advises to prefer ask_pipeworx for casual lookups.

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

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

The description adds extensive behavioral context beyond annotations: safety mechanisms (low-confidence shortcircuit, closed market handling), fan-out logic, response shapes, resolver contract with confidence levels, parent event extraction, news fallback fields, spread illiquidity notes, and resolution-rule risk. It even warns about 'phantom matches' and 'pure-rules loss'. No contradictions with annotations (readOnlyHint, idempotentHint etc.).

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 quite long but well-organized with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each sentence adds meaningful information. It could be slightly more concise, but the structure aids scanning. No fluff or tautology.

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 documents the response shape (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields). It covers safety, edge cases (closed markets, wide spreads, cancellation rules), and usage notes. Virtually all likely agent questions are pre-answered.

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 value: explains that 'market' accepts slug, URL, or question text; 'depth' enum is explained (quick vs thorough); 'include_raw' describes when to use true/false with size implications. Examples are provided in the schema. This goes beyond just repeating parameter 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?

The description immediately states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and explains the process (resolve, classify, fan-out, return evidence + comparison). It provides three input types (slug, URL, question text) and specific use cases. This clearly differentiates from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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"' and gives many fan-out examples. However, it does not mention when NOT to use this tool or directly compare it to sibling tools. Still, the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds valuable behavioral context: it handles off-calendar fiscal years (e.g., AAPL in Sep), sources data from SEC EDGAR/XBRL for companies and FAERS/FDA/trials for drugs, returns sorted results by primary metric, and includes 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?

The description is relatively long but front-loaded with example phrases and key instructions. Every sentence adds information (data sources, sorting, returns). It could be slightly more concise, but it avoids unnecessary words and effectively uses a list-like structure.

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 moderate complexity (2 params, no output schema, but with rich annotations), the description covers what the tool does, what data it retrieves for each entity type, and what it returns (paired data + citation URIs). It is sufficient for an agent to use the tool correctly without additional context.

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

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

Schema description coverage is 100% (both type and values are described). The description enhances the schema by providing concrete examples (e.g., ['AAPL','MSFT'] for company, ['ozempic','mounjaro'] for drug), explaining the meaning of each type and the data it pulls, and reiterating min/max items. This adds semantic clarity beyond the raw schema.

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

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

The description uses a specific verb 'compare' and defines the resource as '2–5 entities' (companies or drugs). It provides example phrases ('X vs Y', 'which is bigger') and clearly distinguishes itself from sibling tools like entity_profile by promising a side-by-side comparison in one call vs. sequential single lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving strong usage guidance. It also lists trigger phrases. However, it does not explicitly mention when not to use it or provide alternatives beyond the implied single-entity lookups.

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

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

Description reveals behavioral traits beyond annotations: account requirement, paid tier needed for certain depth, parallel execution with 4482 tools, expected 15-60s latency, return structure (verbatim evidence, confidence, source, citation, gaps), and limitation that gaps[] when topic not in structured catalog. Annotations already declare readonly, idempotent, open world; description adds substantial context.

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

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

Description is lengthy but well-structured: front-loads account requirement, then core functionality, then usage alternatives, then expected output and timing. Every sentence adds value. Slightly verbose but not wasteful; earns its place.

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

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

Given no output schema, description compensates thoroughly by detailing return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps). Also covers prerequisites, time expectation, and limitations. Complete enough for an AI agent to understand what to expect.

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

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

Schema coverage is 100%. Description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and that thorough needs paid plan, clarifies question parameter accepts broad/multi-part queries because decomposition is inherent. This enriches 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 grounded multi-source research across 1129 structured data sources, decomposing questions into facets and routing to 4482 tools. It distinguishes from siblings by explicitly contrasting with ask_pipeworx for single lookups and breaking news.

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

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

Explicit usage guidance: requires account, free plan via GitHub, paid plan for 'thorough' depth. Clearly states when to use ask_pipeworx instead (if not signed in, for single lookups, for breaking/current news).

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 behavior. The description adds that it returns top-N tools with schemas and examples, ready to call directly, providing useful behavioral context beyond annotations. No contradiction.

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

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

Front-loaded with the main purpose, then lists supported domains efficiently. While slightly long, every sentence adds value and the 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?

Despite no output schema, the description fully explains what is returned (names, descriptions, schemas with examples). Given the tool's simple return model and the context signals (6 params, 1 required, 100% 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 has 100% coverage with descriptions for all 6 parameters. The description mentions aliases for query but adds no new semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states it finds tools by describing data or task, lists many concrete domains (SEC filings, FDA, etc.), and is distinct from sibling tools which are specialized for other operations.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear timing and context for 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 indicate readOnlyHint, idempotentHint, openWorldHint. The description adds value by detailing the fan-out across multiple sources, soft-fail for patents (USPTO sunset), return specifics (up to 5 filings with URIs, fundamentals sorted by period_end DESC). 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 dense paragraph but front-loads example queries and key instructions. Every sentence adds value, though it could be slightly more structured (e.g., bullet points). Still concise and effective.

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

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

No output schema exists, so the description must explain return values. It thoroughly covers returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) along with details like sorting and fallbacks. Given the tool's complexity, this is complete and sufficient.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds nuance: clarifies that 'value' accepts ticker (e.g., 'AAPL') or zero-padded CIK, and that 'type' is only 'company'. Reinforces no names. Adds slight extra meaning over 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 provides a full cross-source profile of a US public company. It lists example queries like 'tell me about X' and summarizes data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields. It distinguishes itself from siblings like resolve_entity by explicitly stating names are not supported.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use (names not supported) and directs to resolve_entity first if only a name is available. This provides 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?

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but no additional behavioral traits beyond 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?

Two sentences, front-loaded with verb and resource, 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 simplicity (1 required param, no output schema), the description covers purpose, usage, and parameter adequately.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. Description concisely refers to 'by key', adding minimal 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?

The description clearly states the verb 'delete' and resource 'memory by key', distinguishing it from siblings like '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 explicit when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with remember/recall, but lacks 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?

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint (false). The description adds value by explaining the tool fetches the page, extracts title/description/key links, and emits standard llms.txt format, going 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 (3 sentences), front-loaded with the main purpose, then details, then use cases. Every sentence adds value, 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?

Given the tool's simplicity (2 parameters, no output schema) and high schema coverage, the description explains the output sufficiently ('single text blob ready to drop at site-root/llms.txt'). It covers what the agent needs to know.

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 adequately defines both parameters (url and max_links). The tool description does not add meaningful extra semantics beyond what the schema provides, thus baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and purpose (for AI crawlers indexing). It distinguishes itself from sibling tools, none of which perform this specific function.

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 (getting a client's site indexed, drafting for own project, auditing competitors). However, it lacks explicit when-not-to-use instructions or alternatives, still clear enough given sibling distinctiveness.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by specifying return fields and default behavior (active only). No contradictions.

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

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

Two sentences with no fluff. Front-loaded purpose, then return fields, then usage guidance. 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?

Given low complexity (one optional param, no output schema), the description adequately covers purpose, return fields, and usage guidance. The lack of output schema is mitigated by listing return fields.

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 description for the sole parameter. Description does not add further meaning beyond the schema, but the parameter is simple and the context is clear.

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 'list' and the resource 'subscriptions', and specifies it returns the caller's active subscriptions. It distinguishes from sibling tools 'subscribe' and 'unsubscribe' by focusing on listing existing subscriptions.

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

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

Explicitly advises to use for reviewing monitored subscriptions before adding more or to find an id to cancel. Provides clear context for when to invoke the 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?

Discloses all relevant behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota. Annotations show readOnlyHint=false and destructiveHint=false, and the description aligns, adding context about usage limits and cost.

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 paragraph that efficiently covers purpose, usage, and constraints. It is front-loaded and every sentence adds value, though a bulleted list could improve scannability.

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

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

Given the tool's moderate complexity (3 parameters, 2 required, nested object), the description fully covers when and how to use it, behavioral limits, and guidance on message content. No output schema exists, so return values are not needed. The description is complete for an AI 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% with detailed descriptions for all parameters. The description adds value by explaining the type enum in plain language and advising to describe issues in terms of Pipeworx tools/packs, which goes beyond the schema's dry definitions.

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: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs and resources, and is distinct from all sibling tools, none of which handle feedback.

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 describes when to use each feedback type (bug, feature, data_gap, praise) and provides a clear exclusion: 'don't paste the end-user's prompt.' This helps the agent decide when to use this tool versus others.

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, etc. Description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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?

Concise paragraph with front-loaded main result, then use cases, then technical details. Every sentence adds value, no redundancy.

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

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

For a tool with one optional parameter and no output schema, the description explains returns, data source, caching, and privacy. Fully covers functionality.

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 explains window semantics well. Description mainly repeats the window options without adding new meaning beyond the schema.

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

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

Clearly states the tool returns top tools, top packs, and total call volume over a window. Uses specific verb ('Returns') and distinguishes from sibling tools like 'discover_tools' by emphasizing it's based on actual call volume from other agents.

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

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

Lists three explicit use cases: discovering hot data sources, confirming popular tool as canonical choice, and seeing if use case aligns with agents. Does not explicitly state when not to use or name alternative tools, but 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: internal logic (monotonicity violations, partition checks), similarity threshold (≥0.30 Jaccard), partition filter (placeholder slugs), fill check against live CLOB depth, and explanation of when not to trade (realizable_edge_pp ≤ 0). 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 lengthy but well-structured with clear sections and front-loaded requirements. It is not overly concise, but every sentence contributes necessary detail for a complex arbitrage tool. Slightly verbose for simplicity but appropriate for the 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?

Despite no output schema, the description describes the response structure (opportunities[] with fields, partition_check object, fill check info). It covers tool behavior, usage conditions, limitations, and alternative tools. The description is complete given the 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%, but the description adds meaningful context: event parameter accepts slugs or full URLs; topic parameter is a seed question. It explains the modes and how each parameter triggers different behavior, adding value 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 explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and the description differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 states the requirement: 'REQUIRES one of event or topic — call with no args fails.' It provides guidance on when to use each mode ('event recommended for a specific market', 'topic for cross-event scanning') and points to an alternative tool ('For custom sizing use polymarket_fill_risk'). It also warns about fill check 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: caching (1h at KV level), model details (lognormal, GDELT), edge calculation (edge_pp_net, slippage), diagnostics for empty segments, and Fed bet exclusion rationale. The description is consistent with annotations; no contradiction.

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

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

The description is a single dense paragraph with excessive technical detail (e.g., sports alpha values, placeholder-slug filter logic). While front-loaded, the length and lack of structure make it hard for agents to quickly parse. It could be significantly shortened and organized into sections.

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 9 parameters, no output schema, and complex behavior, the description is exceptionally complete. It covers all critical aspects: response structure by segment, edge calculation, tradeable-edge knobs, caching, diagnostics, and edge cases like Fed bets. Agents have sufficient information to understand and 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?

Schema coverage is 100% with each parameter described in the input schema. The description adds extra semantics by explaining how parameters interact (e.g., min_partition_leg_kelly vs min_kelly, tradeable-edge knobs), providing rationale (e.g., slippage_pp explanation), and grouping parameters as knobs. This adds 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?

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, explicitly for 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage by focusing on disagreements rather than pure arbitrage, and defines three segments with specific model families.

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 context for when to use the tool ('what should I bet on today') and what it does (discover opportunities without paging). It explains the response structure and tradeable-edge knobs, giving agents clear context. However, it lacks explicit when-not-to-use guidance or direct comparison to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 and idempotent. The description adds context about response structure (tracked, expired, snapshot_dates), limit details (60-day TTL), and that decay comes from daily closes, not intraday. No contradiction.

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

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

The description is somewhat long but well-organized: main question first, then response breakdown, then limits. Each sentence serves a purpose. Could be slightly trimmed, but effective.

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

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

No output schema, so description must fully explain return values. It does so in detail for tracked[], expired[], and snapshot_dates[]. Also covers limits and caveats (TTL, snapshot start, decay from daily closes). Complete for the tool's complexity.

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

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

Schema covers both parameters fully. Description adds defaults (14 days, 1wk window), and clarifies days as lookback and window as snapshot family. This adds useful context beyond the schema.

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

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

The description clearly states that the tool tracks edge persistence and decay, answering 'how long has this edge existed and is it shrinking?' It differentiates from the sibling polymarket_edges (raw current edges) by focusing on historical snapshots.

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

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

The description implies usage for evaluating edge age and decay, contrasting fresh vs old edges. It mentions limits (60-day TTL, snapshot start date) but 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?

Description elaborates beyond readOnlyHint and idempotentHint by detailing order-book walking, return fields, and risk of partial fills. No contradictions with annotations.

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

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

Well-structured with clear sections, but slightly verbose with some repetition of schema details. Front-loaded core purpose.

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

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

Comprehensively covers two modes, parameter constraints, return fields, and usage context despite no output schema. High complexity tool with adequate 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?

Explains mutual exclusivity of market vs event, default values, and interpretation of size_usd in both modes. Schema has 100% coverage, but description adds critical context.

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 identifies tool as realizable-vs-theoretical edge check against CLOB order-book depth, with specific modes (single-market vs basket) and detailed explanation of what it returns.

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: before acting on polymarket_arbitrage signals or trades above ~$500, and explains why (theoretical overround not capturable, partial baskets create directional risk).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds substantial behavioral context: compatibility_warning conditions (non-equivalent bet shapes, no token overlap), temporal_alignment flag, and skipped cross type/subtype counters. No contradictions with annotations.

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

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

The description is well-structured with clear sections for modes, response, and safety fields, and is front-loaded with the core purpose. It is somewhat lengthy but every sentence adds essential detail. Minor redundancy (e.g., repeated 'compatibility_warning' explanations) keeps it from a perfect 5.

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 venues, multiple edge cases) and lack of output schema, the description is thorough. It covers response structure (raw probabilities, spreads), safety fields (compatibility, temporal alignment), and skipped type counters. No additional documentation is needed for basic 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% with all three parameters documented. The description amplifies this by explaining the topic parameter's pre-mapped list and how explicit parameters override topic mapping. It clarifies the two modes and their relationship, adding value 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison. It details two modes (topic shortcuts and explicit pairings) and specifies the output structure.

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 each mode (topic vs explicit) and explains compatibility warnings that indicate when spreads are not tradeable. It sets expectations by noting that most pre-mapped topics currently return warnings. However, it does not explicitly compare to sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scope context (scoped by identifier) and pairing guidance, which is valuable beyond annotations.

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

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

Three sentences, front-loaded with main purpose, and structured logically. Minor redundancy in listing examples, but overall 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?

For a simple read-only tool with one optional parameter, the description provides complete context including scope, usage, and relationship to siblings. No output schema needed given the straightforward return value.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter including the behavior of omitting it. The description does not add additional semantic 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?

The description clearly states the tool retrieves a value previously saved via remember, and that omitting the key lists all saved keys. It distinguishes from sibling tools remember and forget.

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

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

The description explains when to use (look up stored context like user's target ticker, address, research notes) and mentions pairing with remember/forget. It does not explicitly state when not to use, but context is clear.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral context by disclosing that setting mark_read:true modifies read status and that the tool returns specific fields. It does not contradict annotations and provides useful transparency about side effects.

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 reasonably concise with three sentences that are front-loaded with the core purpose. Each sentence adds distinct value, though it could be slightly tighter without losing clarity.

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

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

Given no output schema, the description compensates by naming return fields (source, citation_uri, raw payload). It also covers filtering, mark_read behavior, and alternative access methods. For a tool with 5 optional parameters, this is fairly complete, but could mention limit and unread_only more explicitly.

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 semantic value by providing an example for type ('sec_8k'), specifying the format for since (ISO timestamp), and explaining the effect of mark_read. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returning the most recent alerts. It specifies key fields (source, citation_uri, raw event) and filtering options, effectively differentiating it from sibling tools like list_subscriptions or subscribe.

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 implicit usage guidance by explaining polling works fine and that the same feed is also accessible via a GET endpoint for scripts/dashboards. It also details the mark_read flag behavior. However, it does not explicitly compare to alternative tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral detail: fans out to three sources, fallback logic, soft-fail for USPTO, return structure (changes grouped by source, total_changes, citation URIs). 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?

Description is informative but slightly verbose (e.g., parenthetical notes on API details). However, it is front-loaded with examples and every sentence adds value. Could be trimmed slightly without losing clarity.

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

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

Given no output schema, the description thoroughly explains return structure (changes grouped by source, total_changes, citation URIs), source behavior (GDELT preferred, GNews fallback, USPTO soft-fail), and parameter details. It feels complete for a tool of this complexity.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining since format (ISO or relative) with recommendation ('30d' or '1m'), and clarifies value can be ticker or CIK. This enhances 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 opens with concrete example queries ('What's new with X', 'latest on Y') and clearly states it's a change feed for a company. It explicitly distinguishes from sibling entity_profile, making 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 when-to-use (e.g., 'what happened to Z this week') and when-not-to-use (pointing to entity_profile for static profile). Also describes fallback behavior between GDELT and GNews and notes PatentsView sunset, guiding 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 provide idempotentHint=true and destructiveHint=false; the description adds behavioral details like key-value storage, identifier scoping, and persistence duration (24 hours for anonymous). This adds value beyond annotations, though it omits explicit mention of idempotency, which is acceptable.

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

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

The description is a single, well-structured paragraph that front-loads the purpose and provides all essential information without unnecessary 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?

For a simple 2-parameter tool with no output schema, the description is complete: it explains what it does, when to use, how storage works, persistence behavior, and related tools. No gaps remain.

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

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

Schema description coverage is 100% with clear parameter descriptions (key examples, value as text). The description reinforces the purpose and adds usage context (pair with recall/forget), which 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 clearly states the tool saves data for reuse later, with specific examples (resolved ticker, target address, user preference). It distinguishes from siblings by mentioning 'recall' and 'forget' for retrieval and deletion, making its unique role evident.

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

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

Explicitly states when to use ('when you discover something worth carrying forward') and provides context on scope (key-value pair scoped by identifier) and persistence (authenticated vs anonymous). It also names sibling tools for complementary actions.

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 valuable context that the tool cascades through multiple endpoints and replaces 2-3 manual lookups, going beyond 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 moderately long but well-structured, starting with examples and clear purpose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given the complexity of two entity types and no output schema, the description covers supported types and outputs (ticker, CIK, RxCUI, etc.) adequately. It could be more specific about return formatting but is sufficient for agent usage.

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 both parameters described. The description adds meaning with example inputs (e.g., 'AAPL', 'ozempic') and details what the output includes (ticker, CIK, RxCUI, citation URIs), aiding correct 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 resolves names to canonical/official identifiers using verbs like 'resolve' and 'look up'. It distinguishes from siblings by emphasizing that other tools require these IDs, and provides specific examples for company and drug types.

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 'Use FIRST whenever you have a name but need an ID' and gives triggering examples. It lacks explicit guidance on when not to use, but the context of providing IDs for other tools 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already declare safety. The description adds valuable context: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns ranked list with score, confidence, signal density per entity. 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?

Two concise sentences plus an example. Every sentence adds value. Front-loaded with main purpose. 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?

Given 4 parameters, no output schema, and rich annotations, the description covers usage, parameters, return format, and example. It is fully informative 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%, baseline 3. The description adds meaning: explains 'context' as shared context for disambiguation, and notes that 'entities' first entry is treated as subject for narrative. This goes beyond schema descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with specific verbs ('probes', 'ranks', 'surfaces'). It distinguishes from sibling tools like ai_visibility_check, which likely handles single entities, and compare_entities, which may be more general.

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 usage for competitive AI-marketing audits and provides a concrete example question. Implicitly excludes single-entity checks (handled by ai_visibility_check). The sibling list reinforces the distinction.

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 the annotations (readOnlyHint, idempotentHint, destructiveHint=false), including fanning out to multiple services, graceful degradation with timeouts, and specific latency for bundlephobia's first measurement. 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 relatively concise for its complexity, with a brief core statement followed by structured details. It front-loads the purpose and then provides necessary operational specifics without excessive verbosity.

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

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

Given no output schema, the description thoroughly explains return values (summary block fields, advisories, links, alternatives) and edge cases (partial failure, timeout). This covers all essential information for an 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?

Schema coverage is 100%, and the description adds value by clarifying scoped package acceptance and that version defaults to latest. While some info is redundant, the description enriches understanding of parameter usage.

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

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

The description clearly states the tool's verb ('scan') and resource ('dependency'), specifying it is a composite check for npm packages. It distinguishes itself from sibling tools by explicitly limiting to NPM ecosystem and directing users to deps.dev directly for other ecosystems.

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

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

The description explicitly provides use cases ('is X safe / popular / small') and when not to use it (non-NPM ecosystems with alternatives). This gives clear guidance for agent decision-making.

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, idempotent, and non-destructive. Description adds critical behavioral details: uses BGE-base-en embeddings, cosine over 500-char overlapping windows, 200K char cap with truncation flag. This goes well beyond the annotations.

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

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

Front-loaded with primary purpose, then usage guidance, then technical details. A few extra clauses could be trimmed (e.g., 'BGE-base-en embeddings + cosine...'), but overall the description is well-structured and 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?

Despite no output schema, the description thoroughly explains return values (top-N passages, character offsets, similarity scores), verification use, and technical constraints (200K char cap, truncation). This makes the tool fully understandable 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 description coverage is 100%, so baseline is 3. The description reinforces parameter usage (e.g., 'text you already pulled') but does not add new semantics beyond what the schema already provides for each parameter.

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

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

Description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article). It distinguishes from siblings like ask_pipeworx_grounded by explaining the specific use case of searching within a record instead of grounding over whole document.

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 the record is too big to fit in the prompt. It also gives a direct alternative by pairing with ask_pipeworx_grounded, communicating both the context and the exclusion.

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, etc. The description adds context about the data returned (monthly search volume, competition, CPC from Ads API) and shows an example call. It does not contradict annotations and adds useful 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 three concise sentences plus an example. It is front-loaded with the core purpose, then guidance, then example. 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?

While it explains the data points returned (volume, competition, CPC) and the source, it does not specify the output structure (e.g., array of objects). Since there is no output schema, the description should be more explicit about the return format to be 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% with descriptions. The description adds extra meaning by explaining the _apiKey format (base64 of login:password) and providing an example with default location_code. It also reiterates the keyword limit of 10.

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 exact Google Ads search volume, competition, and CPC for up to 10 keywords, and distinguishes from the sibling tool seo_keyword_overview which is for general SEO volume and keyword difficulty.

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 specifically need Google Ads figures; for general SEO volume + keyword difficulty, prefer seo_keyword_overview (cheaper)', giving clear when and 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 indicate readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: requires OAuth account, returns subscription id, SMS cap, webhook signing and auto-disable, and channel-specific behaviors. 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 thorough with every sentence earning its place, but it is somewhat long. It is well-structured, starting with purpose, then requirements, then types, then delivery. Slightly more conciseness could improve, but still highly effective.

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

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

The tool is complex with 3 parameters (including nested objects), 5 subscription types, multiple delivery channels, and no output schema. The description covers all aspects: type-specific params, delivery constraints, return value (subscription id), and behavioral details. Completely adequate for selection and invocation.

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

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

The description adds extensive meaning beyond the input schema, providing examples and explanations for each enum value in type, detailed shapes and examples for params, and comprehensive delivery channel descriptions including constraints. Schema coverage is 100%, but the description significantly enriches parameter understanding.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream, using specific verbs and resources. It distinguishes itself from sibling tools like list_subscriptions 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 provides explicit when-to-use guidance for each subscription type and delivery channel, including prerequisites (requires Pipeworx OAuth account) and constraints (anonymous/BYO cannot persist, SMS cap, webhook auto-disable). It clearly differentiates the always-on feed from optional channels.

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 explains that the tool returns examples drawn from the live catalog and that it is non-destructive. It adds context about being an onboarding tool with no side effects, fully aligning with and extending the annotations.

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

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

The description is well-structured and front-loaded with common queries, but it is somewhat verbose with lists of categories and examples. Every sentence serves a purpose, but slight trimming could improve precision without losing clarity.

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

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

Given the simple single-parameter schema and comprehensive annotations, the description covers all necessary context: purpose, usage scenarios, return format (category-bucketed examples with tool arguments), and relation to other tools. No output schema exists, but the description adequately describes the output.

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

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

The description elaborates on the single optional parameter by explaining when to omit it (full spread) and how to use it for focus (e.g., 'finance', 'pharma', 'betting'). While the schema lists possible values, the description adds usage context that aids agent decision-making, though it could also include the exact allowed 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 defines the tool as the onboarding entry point for Pipeworx, returning category-bucketed example questions with associated tools. It distinguishes this from sibling tools by stating 'Use this FIRST' and contrasts with similar tools 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 states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also provides guidance on arguments: 'Call with no arguments for the full spread, or pass `topic` to focus.'

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 and destructiveHint=false. The description adds valuable behavioral context: the row is deactivated (not deleted) and historical events remain available via recent_alerts. No contradictions.

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

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

Two sentences, each carrying critical information (action, ownership, deactivation behavior). No unnecessary words, front-loaded with the core purpose.

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

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

For a simple tool with 1 parameter and no output schema, the description covers the essential: what it does, ownership constraint, and what happens to the data (not deleted). No gaps.

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

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

Schema coverage is 100% and the parameter description is clear ('Subscription id (uuid) returned by subscribe'). The tool description reaffirms 'by id' but adds no significant meaning beyond the schema.

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

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

The description uses a specific verb 'Cancel' and noun 'subscription' with clear scope ('by id'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Provides a clear rule: 'Ownership is enforced — you can only cancel your own subscriptions.' This gives context for when the tool can be used. Doesn't explicitly state when not to use, but the ownership constraint is a strong guideline.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details: returns a verdict, structured form, actual value with citation, and percent delta. It also states limitations (v1 supports only specific claim types). 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 trigger phrases upfront, followed by usage context, domain limitations, and return values. Each sentence adds value; no unnecessary repetition. Slightly longer but justified by informative 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 no output schema, the description adequately explains the return values (verdict, structured form, citation, delta). It covers supported domain and limitations. Could mention error handling but overall complete for decision-making.

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

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

The single parameter 'claim' has 100% schema description coverage. The description adds examples and context, clarifying that the claim should be a natural-language factual statement, e.g., about company financials, which goes beyond the schema's brief 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?

Description clearly states the tool's purpose: fact-checking natural-language claims against authoritative sources, with specific examples of trigger phrases. It distinguishes itself from siblings by mentioning it replaces multiple sequential calls, and focuses on company-financial claims.

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 defines the domain (company-financial claims for public US companies) and notes what it replaces, but does not explicitly state when not to use it or suggest alternatives.

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