Rijksmuseum

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

Annotations indicate readOnly, idempotent, openWorld, and non-destructive. The description adds critical behavioral details: default model (Workers AI Llama-3.3-70b), cost implications for Anthropic (BYO key, you pay), and return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 (3 sentences) and front-loaded with the core action. Every sentence adds value. Could be slightly more structured (e.g., bullet points), but it's efficient and 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 explains return structure (per-model fields and combined view). With 4 parameters (1 required), the description covers purpose, usage, param semantics, and behavioral context. It is complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema descriptions: explains what 'entity' is (e.g., brand, product, topic), clarifies 'models' options and default, notes that '_apiKey' is optional and only needed for Anthropic, and explains 'context' helps disambiguate. This is above average value.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility per model. It uses specific verbs ('probe', 'score') and resource ('LLMs', 'visibility'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring and BYO key for Anthropic.

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 mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model and optional Anthropic probing. However, it does not specify when to avoid using this tool or compare directly with alternatives like 'scan_competitor_ai_presence'.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it routes the question to one of 4,476 tools, returns structured answers with pipeworx:// citation URIs, and is a fast entry point. This enriches the behavioral context beyond annotations.

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

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

The description is verbose but each sentence adds value. It is front-loaded with the key directive 'PREFER OVER WEB SEARCH'. However, it could be more concise without losing critical guidance.

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

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

Given the tool's complexity (4,476 tools, 1,127 sources), no output schema, and multiple siblings, the description covers purpose, usage, behavior, parameter semantics, and output format. It is complete enough for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% (all 6 properties described, albeit as aliases for 'question'). The description adds no new parameter semantics beyond what the schema already states. 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 answers factual questions using structured data with citations, lists example domains, and distinguishes from siblings like ask_pipeworx_grounded and deep_research. It is specific about the verb 'ask' and resource 'Pipeworx'.

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

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

Explicitly states when to use this tool over web search ('PREFER OVER WEB SEARCH'), when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions), and provides concrete examples of queries. This is comprehensive 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=true, idempotentHint=true, etc. The description adds valuable behavioral details: costs one extra LLM call, returns explicit refusals for reasons like 'not_in_source' or 'tool_error', and explains the extraction process. 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: first sentence states purpose, then process, return format, use cases, and cost trade-off. Every sentence adds value without redundancy. It is appropriately sized given the complexity of the tool's behavior.

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 provides a thorough explanation of the return format (including fields like evidence, confidence, refusal_reason) and the refusal reasons. This compensates for the missing output schema and ensures the agent understands 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% with all parameters documented (including aliases). The description mentions 'fills arguments' but does not add significant semantic detail beyond the schema. Baseline 3 is appropriate as the schema already provides 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 defines the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific process: routing to the right tool, fetching data, extracting answer solely from results, and returning structured output or explicit refusal. It distinguishes itself from the sibling tool ask_pipeworx by noting the extra LLM call and the refusal logic.

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 for high-stakes domains like financial verdicts) and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). This provides clear decision-making context for the 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, which the description aligns with. Beyond annotations, it details fan-out behavior, response shapes (market, analysis, evidence), resolver contract with confidence levels, parent event extractor, news fallback fields, safety short-circuits, liquidwide spread warnings, and cancellation rule risks. 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 very long (multi-paragraph) and detailed, which is appropriate for complexity but lacks conciseness. It is structured with clear sections (classifiers, fan-out examples, response shapes, etc.) and front-loads the purpose, but could be trimmed for efficiency.

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 (multiple fan-out paths, classifiers, response fields), the description is exceptionally complete. It covers return values (no output schema), edge cases (low confidence, closed markets, wide spreads), resolution risk, news fallback, and parent event details. 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%, so baseline is 3. The description adds significant value: explains depth enum (quick vs thorough), market input types with examples, and include_raw effect on response size (keeps under ~20KB vs 50-500KB). This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifying inputs (slug, URL, question text) and usage scenarios. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage through explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), though not naming alternatives directly.

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

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

The description provides clear when-to-use scenarios and includes safety behaviors (e.g., low-confidence match short-circuits, closed market handling). However, it does not explicitly state when not to use this tool or name alternative tools, leaving agents to infer from sibling list and context.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, non-destructive. Description adds specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs, going 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?

Description is concise yet packed with essential usage patterns, trigger phrases, and data source details. Front-loaded with common queries, no redundant sentences.

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

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

For a tool with no output schema, the description thoroughly explains returned data (metrics per type, sorted results, citation URIs). Covers both entity types, constraints, and replaces 8-15 lookups, making its context 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 for each parameter. Description adds examples ('AAPL', 'ozempic'), clarifies CIK acceptance, and specifies numeric ranges for company tickers, enhancing understanding 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 performs side-by-side comparison of 2-5 companies or drugs, uses explicit trigger phrases like 'X vs Y', and distinguishes itself from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly tells when to prefer this tool: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete examples of when to use it (e.g., comparing financial metrics, adverse events).

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 (readOnly, idempotent, openWorld, non-destructive), the description discloses key behavioral traits: returns a findings packet with verbatim evidence, confidence, source, fetched_at, citation, and gaps[]. It also mentions parallel decomposition, expected latency (15-60s), and that it never invents answers. 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 comprehensive but not overly verbose; every sentence adds value. It is front-loaded with critical account information and usage guidance. Could be slightly tightened, but overall 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?

Given the tool's complexity (parallel research over many sources, no output schema), the description fully covers prerequisites, output format, limitations (news not covered), performance, and alternatives. It distinguishes from 24 sibling tools effectively, making it complete for correct 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 input schema covers both parameters with descriptions, and the description adds significant context: depth enum values explained (quick=3, standard=5, thorough=8) with pricing hint, and question parameter noted as broad/multi-part natural language. This goes beyond schema basics.

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

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

The description clearly states the tool's purpose: 'grounded multi-source research' across 1,127 structured data sources, decomposing questions and routing to tools in parallel. It distinguishes itself from siblings like ask_pipeworx (single lookup) and open-web search, making the purpose specific and unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured data questions, single lookups should use ask_pipeworx, and breaking/current news should prefer ask_pipeworx. It also notes the account requirement and that 'thorough' depth needs a paid plan, with a clear alternative if not signed in.

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 details like returning top-N relevant tools with full schemas and curated examples, and that results are callable directly.

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, front-loaded with core purpose, and contains useful examples and guidance. It is slightly lengthy but every sentence contributes 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 that there is no output schema, the description fully explains the return format (top-N tools with names, descriptions, schemas, examples). It covers all necessary context for a discovery tool with 6 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant extra meaning beyond what the schema already provides for parameters, though it reinforces natural language 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 finds tools by describing data or task, lists many domains, and explicitly distinguishes itself as a first-step discovery tool from siblings that provide direct 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 explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST...', providing clear context for when to use 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?

Annotations are consistent (readOnly, idempotent, not destructive). The description adds behavioral context: patents API sunset May 2025 with soft-fail, parallel fan-out across multiple sources. No contradictions.

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

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

The description is efficient and front-loaded with examples. Somewhat lengthy but each sentence adds value. Could be slightly more structured but is clear and direct.

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

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

Despite no output schema, the description fully details all returned data: CIK, company name, up to 5 filings with URIs, fundamentals, patents, news, LEI. Also explains failure modes for patents. Complete for the tool's domain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that value accepts ticker or zero-padded CIK and that names are not supported. Reinforces the type parameter's limited options.

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 US public companies, with many example queries (e.g., 'tell me about X', 'company profile for Microsoft'). It lists all data sources and fields returned, distinguishing it from siblings 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 to use this tool when a user asks for a holistic view, prefers it over chaining multiple lookups, and notes that names are not supported so to use resolve_entity first. 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 provide destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and stale context, enhancing understanding of the tool's behavioral impact 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?

Three concise sentences: action, use cases, and related tools. No extraneous words or repetition; 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 the tool's simplicity (one parameter, no output schema) and adequate annotations, the description covers key aspects: purpose, usage scenarios, and sibling tools. No gaps identified.

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

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

Schema coverage is 100% and already describes the 'key' parameter as 'Memory key to delete'. The description only mentions 'by key' without adding new semantic detail 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 starts with 'Delete a previously stored memory by key', which is a clear verb+resource+method. It distinguishes itself from sibling tools like remember and recall by indicating it is the deletion counterpart.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with remember and recall. Could add a 'when not to use' but positive guidance is strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it fetches the page, extracts content, and emits markdown, providing clear behavioral context beyond annotations.

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

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

The description is concise, with three sentences plus a bullet list of use cases. It is front-loaded with the main action and contains no superfluous 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?

With two well-schemaed parameters and no output schema, the description explains the output format and usage. It provides sufficient context 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 descriptions for both parameters. The description mentions 'any URL' but adds no further meaning beyond schema for max_links. Baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using specific verbs and resources. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation for AI crawler indexing.

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 projects, or auditing competitors. It does not explicitly state when not to use but offers clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns specific fields and defaults to active subscriptions, providing additional 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 sentences, no unnecessary words, front-loaded with purpose and output 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?

Tool is simple (one optional param, no output schema). Description fully covers what it does, returns, and 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?

Schema covers 100% of parameters with clear descriptions. Description mentions 'active' which hints at include_inactive but doesn't add new meaning beyond schema.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel', linking to sibling 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 are limited (readOnlyHint=false), but description adds critical behavioral details: free, doesn't count against tool-call quota, rate-limited to 5 per identifier per day, and signals affect roadmap. No contradiction with annotations.

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

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

Description is comprehensive but still concise. Every sentence contributes meaningful information. Could be slightly tighter but overall well-structured and 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?

Despite no output schema, description covers expected behavior: what to include, rate limits, quota, and team use. It addresses likely agent questions about usage constraints and impact fully.

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

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

Schema coverage is 100%, but description adds value beyond schema: for 'message' it specifies typical length (1-2 sentences, 2000 chars max) and asks for specifics. For 'context', it clarifies optional structured context. The 'type' parameter is well-documented in schema, so description adds less there.

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 sending feedback about bugs, missing features, or praise, using a specific verb 'Tell' and resource 'Pipeworx team'. It distinguishes from sibling tools which are all research/analysis tools, not 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 lists when to use (bug, feature/data_gap, praise) and what to avoid (paste end-user prompt). States rate limit and quota-free nature, providing clear guidance on appropriate usage.

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

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

The description transparently discloses the tool's behavior: aggregated from analytics, no PII, cached with varying freshness. This adds significant value beyond the annotations, which already indicate read-only, idempotent, non-destructive.

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, front-loaded with the core function, and uses bullet points for clarity. Every sentence provides 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?

The description covers all essential aspects: purpose, usage context, parameter semantics, behavioral transparency. The only gap is lack of explicit output structure, but the description clearly states what the tool returns (top tools, top packs, call volume), which is adequate for an agent to interpret the response.

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

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

The description explains the semantic difference between short and long windows, enriching the parameter meaning beyond the schema's enum definition. With 100% schema coverage, this extra context elevates the parameter semantics.

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

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

The description clearly states the tool returns trending data (top tools, packs, call volume) with configurable time windows. It explicitly lists three use cases, making its purpose distinct from sibling tools like discover_tools or ask_pipeworx.

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 three specific use cases that guide when to invoke this tool, such as discovering hot data sources or confirming canonical choices. However, it does not explicitly contrast with 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?

The description discloses extensive behavioral traits beyond annotations, including that it requires exactly one of two modes, walks child markets, computes checks with specific thresholds (Jaccard ≥0.30, deviation >3pp, placeholder fraction >20%), and performs a fill check using live CLOB depth. 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-organized with front-loaded requirement, separate mode explanations, and clear sections for semantic anchor, partition filter, and fill check. It is slightly verbose but every sentence adds value, earning a 4.

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

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

Given the complexity of the tool (two modes, multiple checks), the description is comprehensive: it covers all input parameters, explains processing logic with specific thresholds, describes the output structure, and references a sibling tool for custom sizing, making it complete despite no 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?

Schema has 100% description coverage, and the description adds significant meaning by providing examples of slugs and seed questions, explaining how each mode behaves, and detailing output fields like partition_check and fill results.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, distinguishing between event mode and topic mode, which clearly differentiates it from siblings.

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

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

The description clearly states the requirement for one of 'event' or 'topic', recommends 'event' for specific markets, explains cross-event mode catches broader patterns, and mentions 'For custom sizing use polymarket_fill_risk' as an 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), response structure (by_segment, diagnostics), caching (1h KV), and edge computation details (net slippage, Kelly). 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 long but well-organized: front-loaded purpose, then model segments, response top-level, and knobs. Every sentence adds essential detail. Slightly verbose but avoids redundancy; could be trimmed without losing clarity.

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

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

Given 9 parameters, no output schema, the description fully covers return fields (by_segment, fed_candidates, diagnostics) and explains why empty segments occur. It addresses complex scenarios like partition arbs and concentrated longshots. Complete for agent 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?

Schema coverage is 100%, but the description adds value beyond param descriptions by explaining how knobs like min_partition_leg_kelly work in context of partition arbs, and provides usage examples (e.g., setting max_spread_pp to 2). It clarifies relationships between parameters and business logic.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' and explicitly frames it as a 'what should I bet on today' tool, clearly distinguishing the purpose from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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 tradeable-edge knobs (min_liquidity, max_spread_pp) and caching behavior. It provides guidance on parameter tuning (e.g., adjusting slippage for thin partitions). However, it does not explicitly contrast with sibling 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 declare read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: response structure, decay computation, snapshot gaps, TTL limits, intraday caveat. 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?

Well-structured with clear sections. Slightly lengthy but every sentence adds value. Front-loaded with purpose, then detail, then limits.

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

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

No output schema, but description fully explains response fields (tracked, expired, snapshot_dates) and their semantics. Covers parameters, usage, and limitations comprehensively.

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 practical context: default values, max days, snapshot family meaning, and ties parameters to response structure.

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

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

Clearly states it provides 'Edge persistence and decay telemetry' and answers a specific question. Distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis.

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

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

Explains use case with concrete example (fresh vs old edge). Does not explicitly list alternatives but context implies when to use this versus 'polymarket_edges'.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds substantial context: 'walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled...' and warns about thin books and partial fills converting arb into unhedged directional positions. 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 lengthy but well-structured, using clear section breaks for single-market and basket modes. All sentences add value, though some could be slightly more concise. Front-loads core purpose effectively.

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 no output schema, but the description comprehensively explains all return fields for both modes, including edge cases like thin_legs, forced_directional_risk, and max_clean_notional_usd. Given the tool's complexity, the description is complete and covers critical warnings.

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

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

Schema description coverage is 100% with descriptions for all 4 parameters. The tool description adds further meaning: explains how size_usd is interpreted differently for single-market vs basket modes (max spend on buys, target proceeds on sells vs settlement notional), defaults, and clamping range. This is beyond what the schema provides.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes, and provides specific verbs and resources. It differentiates from sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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 on when to use: before executing arbitrage signals or trades above ~$500. Explains why with risk details: 'theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'. Also distinguishes between single-market and basket modes, giving context for each.

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 covers behavioral traits beyond annotations: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross-type/subtype counters. Annotations already mark it read-only, idempotent, and non-destructive; there's 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 verbose but well-structured with clear sections (modes, response, safety fields). Every sentence is informative, though some could be tightened 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, the description thoroughly explains the response structure (leg prices, top_spreads_pp, safety fields) and edge cases. Given the high schema and annotation coverage, it is complete and actionable for an AI agent.

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

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

Schema coverage is 100% with well-described parameters. The description adds value by explaining the two modes and providing examples, going beyond the schema's property descriptions.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket, detailing its two modes (topic shortcuts and explicit tickers) and output. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on venue comparison.

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

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

The description explains when to use each mode and warns that most pre-mapped topics currently return compatibility_warning, setting appropriate expectations. While it doesn't explicitly compare to other tools, 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 already declare readOnlyHint=true and destructiveHint=false. Description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. No contradictions.

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

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

Description is compact (4 sentences) with no fluff. First sentence states the core function, second provides use cases, third explains scoping, and fourth pairs with sibling tools. 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?

No output schema exists, but the description adequately explains the two possible returns (value for a specific key, or list of all keys). It covers scoping and pairing with remember/forget. Could mention error handling but otherwise complete for a simple lookup 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 a description for the key parameter. The description adds meaning beyond the schema by explaining that omitting the key lists all saved keys, reinforcing correct 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?

Description clearly states the tool retrieves a value previously saved via remember, or lists all saved keys if the key argument is omitted. It distinguishes itself from sibling tools remember and forget by specifying its role as a lookup operation.

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

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

Description explicitly says when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also implies when not to use by pairing with remember and forget for save/delete actions. Scoping is disclosed.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds context: mark_read behavior (flags returned events read so next call shows newer), polling compatibility, and external URL for scripts. 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 concise (4 sentences), front-loaded with the core purpose, and every sentence adds useful information 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?

Considering 5 parameters, no output schema, and rich annotations, the description covers the return format, filtering options, mark_read functionality, and even an alternative access method. It is fully adequate for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read ('so the next call only shows newer ones') and clarifying the since parameter (ISO timestamp) beyond the schema's basic 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 pulls fired events from the subscription feed and specifies returned fields (source, citation_uri, raw event payload). It distinguishes from sibling tools like list_subscriptions, which manage subscriptions, by focusing on reading alerts.

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

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

The description provides guidance on when to use the tool ('Polls work fine') and mentions an alternative access method (registry.pipeworx.io/alerts.json). However, it does not explicitly contrast with other reading tools among siblings.

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

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

Description adds behavioral context beyond annotations: fans out to multiple sources, fallback to GNews on rate limits, USPTO soft-fail, returns structured changes with citation URIs. No contradiction with annotations.

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

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

Description is dense and informative but has a slight redundancy in listing example queries. Still, it is well-structured and 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?

Given no output schema, description explains return format (changes grouped by source, total_changes, citation URIs). Covers sources, fallback, and USPTO sunset. Combined with annotations, 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%, but description adds meaning: explains type is only 'company', since format with examples and relative shorthand, value can be ticker or CIK. Enhances schema 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 is a change feed for a company, listing data sources (SEC, GDELT, GNews, USPTO) and examples like 'What's new with X'. It distinguishes from sibling tools like entity_profile by explicitly mentioning the alternative for static profiles.

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 via example queries and explicitly tells when not to use: 'Use entity_profile instead when you want the static profile...'. This guides the agent effectively.

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 key behavioral traits: key-value storage, scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). It aligns with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and adds context beyond them.

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

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

Three sentences: purpose, usage guidelines, behavioral details. Every sentence adds value, and the most critical information (what it does) is front-loaded. 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 simple input schema and no output schema, the description covers all essential aspects: purpose, usage, duration, and pairing with recall/forget. It leaves no critical gaps for correct tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining key naming conventions (e.g., 'subject_property') and stating value can be any text, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference). It distinguishes from sibling tools recall and forget by explicitly mentioning 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?

The description specifies when to use: 'Use when you discover something worth carrying forward' and notes persistence differences for authenticated vs anonymous sessions. It lacks an explicit 'when not to use', but the positive guidance is strong.

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 safety, but the description adds significant context: internal cascading through multiple endpoints, auto-disambiguation, and return formats. This discloses complexity and expectations 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 a single paragraph that front-loads with user questions and efficiently packs examples and details. It is concise without being terse, though a bulleted list could improve scannability slightly.

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, input formats, output details for each type, and internal behavior. No output schema exists, so description compensates well. Lacks explicit error handling or not-found behavior, but overall complete for a read-only 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 detailed descriptions for both parameters. The description adds minimal new semantics beyond the schema, except for 'auto-disambiguated' and output expectations which are not parameter-specific. 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 resolves names to canonical identifiers, with specific examples. It distinguishes itself by being the go-to for name-to-ID conversion, and lists supported entity types. No sibling tool directly competes, so differentiation is inherent.

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.' This is a strong when-to-use guideline. It also implies when not to use (if you already have an ID) but could be more explicit. It provides context for replacement of manual lookups.

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

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

Annotations indicate safe, read-only, idempotent, non-destructive behavior. Description adds that it probes each entity with ai_visibility_check, ranks, and returns score/confidence/signal density. Also notes first entity is the 'subject' for narrative. No contradictions.

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

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

Two sentences plus a brief parenthetical example. Front-loaded with the main action. Every sentence adds critical information 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?

No output schema, but description explicitly states return fields (ranked list with score, confidence, signal density). Explains purpose relative to sibling tools. Covers entity count constraint from schema. Complete for agent understanding.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining that the first entity in the 'entities' array is treated as the subject for narrative, which is not in the schema. Also implies the ordering matters.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and surfacing most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly says 'useful for competitive AI-marketing audits' and gives an example question. Does not specify when not to use or name alternatives, but the context of comparing competitors relative to a subject 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses partial failure behavior, the 5-30s timeout for first bundlephobia measurement, and that sources_failed lists timed-out sources. 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?

Concise, front-loaded with purpose, then usage, then behavioral nuances, then ecosystem constraints. Every sentence is informative with no waste.

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

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

Given complexity (multiple data sources, partial failures, no output schema), the description fully explains output summary, return value structure, and ecosystem limitations. 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%, but the description adds context: scoped packages accepted, version defaults to latest. Adds marginal 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 performs a composite check on npm packages using deps.dev and bundlephobia to answer questions about safety, popularity, and size. It differentiates from siblings by specifying NPM ecosystem only.

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

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

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

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

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

Annotations indicate readOnly, idempotent, etc. The description adds significant behavioral detail: uses BGE-base-en embeddings with cosine similarity over 500-char windows, 200K char cap with truncation and flagging, and returns passages with offsets and 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?

The description is concise (6 sentences) and well-structured: purpose, when to use, pairing suggestion, technical details. Every sentence adds value without repetition.

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

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

Despite no output schema, the description explains return values (top-N passages with offsets and similarity scores), technical internals, and constraints. It is fully adequate for an agent to understand the tool's behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing example queries for the query parameter and clarifying the limit range and default, though most parameter meaning is already in the schema.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb (search), resource (text inside a fetched record), and provides examples. It differentiates from sibling tools by noting it pairs with ask_pipeworx_grounded for grounding over passages.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also explains the benefit of returning passages with offsets for verification, providing clear context without excluding 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 (idempotent, not read-only, not destructive), the description discloses important behavioral traits: OAuth requirement, 10/day SMS cap, webhook auto-disable after 10 failures, and one-time webhook secret. This adds significant value that annotations alone do not 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 well-structured and front-loaded: main purpose, prerequisites, types, then delivery. Every sentence contributes meaningful information with no fluff, achieving high information density while remaining readable.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers prerequisites, type details, and delivery behavior thoroughly. It mentions the return value (subscription id) but could be slightly more explicit about the full response structure, though the one-time webhook secret is noted.

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?

While schema coverage is 100%, the description adds rich examples for each subscription type (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and elaborates on delivery options with practical constraints and instructions. This goes well beyond the schema's brief descriptions.

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

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

Description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. This verb+resource combination is specific and distinct from sibling tools like list_subscriptions or 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 clear usage context by noting the requirement for a Pipeworx OAuth account and listing supported subscription types and delivery channels. However, it does not explicitly contrast with alternatives or state when not to use 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by explaining the return structure (category-bucketed with tool+argument shapes) and that it draws from a live catalog. No contradiction with annotations.

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

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

The description is well-structured with a clear purpose at the start, followed by details and usage instructions. It is somewhat long but every sentence adds value. Slightly more concise could be possible, but it's 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?

Given no output schema, the description adequately explains the return format (category-bucketed example questions with tool shapes), how to use the topic parameter, and when to invoke the tool. It is complete for a simple tool with one optional parameter.

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 topic values (finance, pharma, etc.) and clarifying that omitting the parameter gives a full spread, which goes beyond the schema's simple 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 returns category-bucketed example questions, serving as the onboarding entry point for Pipeworx. It uses specific verbs ('returns') and resource ('example questions'), and distinguishes from sibling tools by being the first point of contact for new users.

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 this FIRST when you do not yet know what Pipeworx can do' and provides alternatives like ask_pipeworx, entity_profile, etc. It also explains when to pass the optional 'topic' parameter.

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 details beyond annotations: it explains that subscriptions are deactivated (not deleted) and ownership is enforced. Annotations are consistent, and there is 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 concise with two sentences, front-loading the action. Every word adds value without redundancy.

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

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

For a simple mutation with one parameter and no output schema, the description covers all necessary behavioral aspects: action, ownership constraint, and deactivation semantics.

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

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

Schema description coverage is 100% for the single parameter 'id.' The description adds context about ownership (the id must be the user's own), which extends beyond the schema's basic type information.

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

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

The description clearly states 'Cancel a subscription by id,' using a specific verb and resource. It distinguishes the tool from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description provides important context: ownership enforcement and row deactivation. However, it does not explicitly state when to use this tool versus alternatives, leaving some implicit guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by detailing the return verdict types (confirmed, refuted, etc.), extracted structured form, actual value with citation, and percent delta. It also discloses the internal data source (SEC EDGAR + XBRL) and scope (company-financial claims). No contradiction with annotations.

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

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

The description is moderately long but well-structured. It front-loads with typical query patterns, then states purpose, scope, output format, and value proposition. Every sentence provides useful information, though slightly verbose; a 4 is appropriate.

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

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

Given the tool has only one parameter and relies on annotations for safety, the description is comprehensive. It covers the return format, supported claim types, and limitations (v1, company-financial for US public companies). No output schema is needed as the description explains the response structure.

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 significant meaning: it explains what constitutes a valid claim, gives examples, and describes the internal processing pipeline (NL parsing → entity resolution → data lookup → numeric comparison). This is far 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?

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes typical user query patterns ('Is it true that...', 'fact check') and specifies the resource (claim) and action (validate). It also distinguishes from siblings by noting it replaces 4–6 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 constrains usage to company-financial claims for public US companies via SEC EDGAR + XBRL. It does not name alternative tools but provides clear context, earning a 4.

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