Emoji Oracle

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context: the default model is free, Anthropic probing requires a BYO key with direct payment to Anthropic, and the return structure includes per-model and combined views.

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 three sentences, front-loaded with the action and result. It efficiently packs key information without wasted words, though slightly more structure could improve readability.

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 adequately outlines the return format (per-model score, confidence, signals, raw_response, and combined view). It covers parameter usage, model selection, and use cases. Minor omission: no mention of limits or pagination, but not critical for a probe 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 description coverage is 100%, but the description adds meaning beyond parameter descriptions: it specifies the default model for the 'models' parameter and clarifies that '_apiKey' is passed straight through to Anthropic's API.

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 specifies a clear verb ('probe', 'score') and resource ('LLMs', 'visibility'). It distinguishes itself from sibling tools by explicitly stating its purpose: scoring visibility (0-100) per model, which is different from scanning or comparing entities.

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

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

The description gives clear usage context: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default model and when to provide an API key, but does not explicitly exclude scenarios or compare to sibling tools 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool routes to 3,751 tools and returns stable pipeworx:// citation URIs, which is useful behavioral context beyond annotations.

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

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

The description is relatively long but front-loaded with the key directive 'PREFER OVER WEB SEARCH'. Every sentence adds value: lists data domains, explains routing mechanism, provides query patterns and examples. Could be slightly more concise, but structure is 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 the tool's complexity (meta-tool over 3,751 tools across 886 sources), the description is remarkably complete. It covers purpose, usage guidance, behavior, and return format (structured answer with citation URIs). No output schema, but the description adequately explains what the user gets.

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 each alias (q, text, input, query, prompt) described as alias for question. The description doesn't add parameter semantics beyond what the schema already provides, so 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 uses specific verb 'routes the question' and resource '3,751 tools across 886 sources', clearly distinguishing from siblings like ask_pipeworx_grounded. It lists concrete data domains and examples, making the purpose unmistakable.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides detailed criteria: factual questions about real-world entities, events, or numbers. Includes examples like 'current US unemployment rate' and lists query patterns ('what is', 'look up', etc.), giving clear when-to-use guidance.

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

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

Discloses extra LLM call cost, return format with refusal reasons (not_in_source, no_tool_match, etc.), and the process of using only tool results, supplementing annotations (readOnlyHint, idempotentHint) with actionable 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?

Front-loaded with core purpose, efficient in conveying process and return format, but could be slightly more concise (e.g., 'Same routing as ask_pipeworx' is fine but adds slight 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?

Fully describes return values and error modes despite no output schema, covers use cases, and provides all context needed for an AI agent to decide 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 applies. Description does not add semantics beyond what schema provides (all aliases for question are covered); no additional meaning needed.

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 it is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, clearly distinguishing from the sibling tool 'ask_pipeworx' via cost and use case.

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

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

Provides explicit when-to-use ('Use whenever an answer will be quoted, cited, or acted on...') and when-not-to-use ('prefer ask_pipeworx for casual lookups') with rationale (cost difference).

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 detailed behavioral traits beyond annotations: low-confidence resolutions short-circuit, closed markets return status, wide-spread markets get illiquidity warnings, and resolution-rule risk is parsed. These are not evident from annotations (readOnlyHint, etc.) and add critical context for safe agent invocation.

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 detailed but excessively long and dense, mixing examples, edge cases, and response shapes in paragraphs. While the main purpose is front-loaded, the length may overwhelm agents. Structuring with bullets or shorter sections would 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 tool's complexity (classifiers, fan-out, multiple data sources, edge cases), the description is remarkably complete. It covers input resolution, resolver contract, parent_event extraction, news fallback, safety mechanisms, and resolution-rule risk. No output schema exists, but response shapes are thoroughly described.

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

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

All three parameters are described in the input schema (100% coverage). The description adds significant value: for 'market', it explains acceptable inputs (slug, URL, question text); for 'depth', it clarifies quick vs thorough; for 'include_raw', it explains when to use true (recompute deltas). This exceeds the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (bet, Pipeworx data), and output. It distinguishes from sibling tools by focusing on betting research with data fan-out, unlike general query tools like 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?

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also warns about low-confidence matches and closed markets. However, it does not explicitly compare to siblings or state when NOT to use this tool, which would improve clarity.

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 (read-only, open-world, idempotent, non-destructive), the description adds rich behavioral details: single parallel call, correct handling of off-calendar fiscal years, data sources (SEC EDGAR/XBRL, FAERS), automatic sorting, and 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 front-loaded with usage examples and efficiently conveys purpose and behavior. It is thorough but not overly verbose; every sentence adds value. Minor trimming possible but overall well-structured.

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

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

Given the tool's complexity (multiple data sources, cross-type behavior, sorting, citations) and no output schema, the description is remarkably complete. It covers input semantics, behavioral nuances, and output format (paired data + URIs), enabling correct agent invocation.

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

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

Schema coverage is 100%, but the description significantly enriches parameter meanings: example tickers/drug names, constraints (2-5), what each type fetches, and that results are sorted by primary metric. This adds substantial 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 'side-by-side comparison of 2–5 companies or drugs', uses specific verbs like 'compare' and includes common query examples. It clearly distinguishes this tool from single-entity lookups (e.g., entity_profile) by highlighting parallel execution.

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

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

The description includes 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage guidance. It explains the data sources for each type, but does not explicitly mention when not to use it or alternatives beyond the preference statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds critical behavioral details: never invents facts (gaps[] for unknowns), returns verbatim evidence with confidence/source/timestamp/citation, and expected response time of 15-60s. 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 thorough but efficient, front-loading the core purpose in the first sentence. Every sentence adds value, though it could be slightly more concise without losing key information.

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

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

For a complex tool with no output schema, the description fully explains the process (decomposition, parallel routing), output structure (findings packet with citations, gaps[]), constraints (account, paid plan), and expected latency. Complete enough for effective 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 descriptions for both parameters. Description adds value by explaining the meaning of depth levels (quick=3, standard=5, thorough=8) and clarifying that the question parameter accepts broad/multi-part input. This goes beyond schema enum 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 performs grounded multi-source research by decomposing questions into sub-questions and parallel routing. It distinguishes itself from siblings like ask_pipeworx (single lookup) and compare_entities (specific comparison), providing a specific verb and resource.

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

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

Explicitly states when to use (broad/multi-part questions) and when not to (single lookups, directing to ask_pipeworx). Provides example questions and specifies requirements (Pipeworx account, paid plan for 'thorough' depth). Clear context and alternatives.

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

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

Description adds useful behavioral detail beyond annotations: returns top-N relevant tools with schemas ready to call. Annotations already cover non-destructive, idempotent, read-only nature.

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, 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?

Given no output schema, description adequately explains return format (top-N tools with schemas). Parameters explained clearly.

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

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

Schema coverage is 100% with clear descriptions. Description provides aliases and example queries, adding value beyond schema.

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

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

The description clearly states the tool finds tools by describing data/task, lists domains, and distinguishes from siblings by stating 'Call this FIRST' for browsing options.

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 guidance to use when needing to browse/discover tools, and to call FIRST when many tools available. Implicitly advises against using when you already know the specific 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, destructiveHint – so the safety profile is fully covered. The description adds that it returns 'cryptic emoji prophecy with vibe rating' but doesn't add behavioral context beyond what annotations provide. 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 sentences with zero waste. First sentence states the action and optional feature, second states the return value. Front-loaded with key info.

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

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

Given the tool has an output schema (context says true) and annotations cover safety, the description is complete enough. It explains what it does and what it returns. For a simple oracle tool, 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 description coverage is 100% – the schema already describes all three parameters. The description mentions 'optionally request interpretation' and 'emoji count' but doesn't add new details beyond what's in 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 the tool's purpose: ask a question and receive an emoji prophecy with vibe rating and optional interpretation. It uses specific verb 'ask' and resource 'Emoji Oracle', and the uniqueness is evident given sibling tools are all serious/practical.

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

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

The description implies usage context by saying 'Ask the Emoji Oracle a question' – it's clearly a whimsical tool. No explicit when-not-to-use or alternatives, but given sibling tools, the differentiation is clear. Could benefit from a note about not using for factual answers.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the parallel fan-out across multiple APIs, soft-fail for patents, and fallback mechanisms for news. 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 examples and a clear 'ALWAYS PREFER' directive. It uses semicolons and lists to organize information efficiently. Minor redundancy could be trimmed, but it earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly lists all return fields: cik, company_name, recent_filings with URIs, fundamentals with specific metrics, patents, news, and LEI. For a tool with two params and no output schema, this is highly complete.

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

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

Schema coverage is 100%; both parameters are described. The description adds meaning by providing examples (e.g., 'AAPL', '0000320193'), clarifying that names are not supported, and referencing resolve_entity as a prerequisite. This goes 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's purpose: 'full cross-source profile of a US public company in ONE parallel call', with specific examples of user queries. It lists all data sources and outputs, and distinguishes from sibling tools like resolve_entity by explaining that 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?

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells when not to use: 'names not supported (use resolve_entity first if you only have a name).'

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 confirms deletion ('Delete') and adds context about clearing sensitive data, which aligns 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?

Two concise sentences: first states action and resource, second gives usage guidelines. No filler, front-loaded with key information.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, usage context, and relationship to sibling tools. No missing aspects.

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

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

Schema coverage is 100% with description for 'key' as 'Memory key to delete'. Description does not add extra semantics beyond schema, but baseline 3 is appropriate since schema already describes the parameter sufficiently.

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

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

Clearly states 'Delete a previously stored memory by key.' The verb 'Delete' specifies the action, 'memory by key' specifies the resource and method. Distinguishes from sibling tools 'remember' and 'recall' by being the inverse 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?

Explicitly provides three scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with sibling tools ('remember and recall'). No when-not-to guidance needed given simplicity.

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

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

The description discloses the behavior beyond annotations: fetches the page, extracts title/description/key links, and emits standard llms.txt format. Annotations already indicate safety (readOnly, idempotent), and description adds actionable detail. No contradiction.

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

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

Three sentences, each carrying distinct value: purpose, process, and use cases. No fluff, front-loaded with key information.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers purpose, usage, behavior, and output. 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 coverage is 100%, so the description does not need to add much. It restates the url parameter's purpose and mentions default/max for max_links, but the schema already includes those details. Baseline score 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 (URL), and output format. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation.

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 three use cases: indexing client sites, personal projects, and auditing competitors. However, it does not mention when not to use or provide alternatives, though the context makes it 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 include readOnlyHint, idempotentHint, destructiveHint. Description adds return field details but no behavioral context beyond what annotations provide. 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 sentences, no fluff. Front-loaded with core purpose, immediately followed by usage hint and return fields. 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?

No output schema, but description lists six return fields adequately. Single optional parameter is simple. No missing critical context for a list 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 description coverage is 100% with parameter 'include_inactive' described. Baseline 3 applies since description does not add further 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 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields. It distinguishes itself 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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context. No explicit exclusion of alternatives, but enough guidance for typical 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?

The description adds significant behavioral context beyond annotations: rate limit of 5 per identifier per day, free usage, no quota impact, daily digests, and roadmap influence. Annotations provide no contradictions; they are consistent with the writing nature.

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 but well-structured: purpose first, then usage guidelines, then behavioral details. Every sentence earns its place; no fluff. It is appropriately sized for the complexity.

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

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

Given no output schema, the description does not need to explain return values. It covers all necessary aspects: when to use, what to include, rate limits, and impact. It is fully complete for guiding correct tool 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?

Schema coverage is 100%, so parameters are well-documented. The description adds value by explaining the enum meanings (bug, feature, etc.) and advising on message content (be specific, 1-2 sentences). It does not repeat schema details unnecessarily.

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: to send feedback about bugs, features, data gaps, or praise to the Pipeworx team. It distinguishes itself from sibling tools by being the only feedback channel, and the description is specific about the resource (Pipeworx team) and action (send 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 provides when to use: for bugs, features/data gaps, or praise. It also gives negative guidance: don't paste the end-user's prompt, describe in terms of Pipeworx tools/packs. This helps the agent decide correctly.

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, etc. The description adds context: self-aggregating signal, no PII, derived from CF analytics engine, and cached. 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 bullet-pointed use cases. Every sentence adds value; concise 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?

For a simple read-only tool, the description covers purpose, parameters, return values (top tools, packs, volume), and caching. No output schema needed. Completely adequate.

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 well-described enum. The description adds meaning by explaining the trade-off between window lengths (hot vs steady-state), enhancing 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 returns top tools, top packs, and total call volume over a recent window, using specific verbs and resource. It distinguishes from siblings like discover_tools by focusing on aggregate trends.

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 three use cases and mentions caching behavior. Does not provide explicit when-not-to-use instructions, but the context is clear enough for selection.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: internal checks (monotonicity, partition, Jaccard similarity, placeholder filter), fill check against live order book, and conditions like 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade'. No contradiction with annotations.

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

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

The description is fairly long but well-structured with labeled sections (REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, Response, FILL CHECK). Front-loaded with the key requirement. Some detail on internal logic might be excessive, but it remains readable and organized.

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

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

Given no output schema, the description thoroughly explains the response fields (gap_pp, suggested_trade, reasoning, etc.) and the fill_check sub-response. It covers edge cases like placeholder slugs and low similarity, making it self-contained for correct invocation and interpretation.

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 describes both parameters with 100% coverage. The description adds meaningful context: examples of valid slugs and seed questions, mode differences, and implicit requirement that at least one must be provided. It also explains the difference in the response structure between modes.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between event and topic modes with specific examples, making it easy to understand among sibling tools.

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

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

The description explicitly guides when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also warns that calling with no arguments fails. However, it does not explicitly contrast with sibling tools like polymarket_edges, though it does reference polymarket_fill_risk for sizing.

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 internal models (e.g., lognormal barrier, news momentum), caching (1h), response structure (by_segment, diagnostics), and caveats (Fed data unreliability). Annotations already indicate read-only/idempotent nature, and the description adds substantial behavioral context without contradiction.

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

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

The description is verbose but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loaded purpose. Every sentence adds value, though some redundancy could be trimmed.

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 (9 parameters, multiple models, segments, diagnostics), the description covers all aspects: purpose, usage, behavioral traits, parameter semantics, and output structure (by_segment, diagnostics). No output schema exists, but the description adequately explains return values.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema by explaining each parameter's role, defaults, and interactions (e.g., min_kelly vs min_partition_leg_kelly). This enhances the agent's ability to configure the tool correctly.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is built for daily opportunity discovery. It distinguishes from siblings by detailing model-driven, structural arbitrage, and concentrated longshot segments.

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

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

The description provides clear guidance on when to use the tool and detailed explanations of parameter adjustments (e.g., tradeable-edge filters). However, it does not directly contrast with siblings like polymarket_arbitrage for pure arbitrage needs.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds significant behavioral detail: it reads from daily snapshots written on cache-miss, explains output fields (tracked, expired, snapshot_dates) and computations (trend, decay). 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 relatively long but each sentence adds substance. It front-loads the core purpose, then details output fields and limitations. Could be slightly more concise, but no wasted sentences.

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

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

Given no output schema, the description thoroughly explains return fields (tracked, expired, snapshot_dates) with detailed interpretations. Annotations cover safety. The description is complete for a read-only telemetry 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?

Input schema covers both parameters with descriptions. The description adds context like default values (days=14, window='1wk') and clamping (days 2-30). Schema coverage is 100%, so baseline is 3; the description adds value beyond schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from siblings like 'polymarket_edges' by focusing on time-series and decay analysis.

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

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

The description gives clear context for when to use (to understand edge history, trend, decay) and notes limitations like 60-day TTL and intraday not covered. Could be more explicit about when not to use, but it's well-defined.

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, so the safety profile is clear. The description adds rich behavioral context: it walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is well-structured with bold headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loads the core purpose. However, it is somewhat lengthy; some details (e.g., listing all return fields) could be condensed since schema coverage is 100%. Still, every sentence earns its place.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is remarkably complete. It explains all return values (top_of_book, vwap_fill_price, slippage_pp, etc.), verdict options, and even warns about thin legs and forced directional risk. No gaps remain 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 description coverage is 100%, but the description adds significant meaning beyond the schema: it explains how parameters are interpreted differently in single-market vs. basket modes (e.g., size_usd as spend vs. target proceeds vs. settlement notional), and explains the default behavior for side in basket mode. This adds crucial context for 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges), making its role unique and specific.

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

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

The description provides explicit guidance on when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the consequences of not using it (partial basket fills convert arb into unhedged directional position), giving clear context for use vs. alternatives.

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

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

The description goes well beyond the annotations (readOnlyHint, etc.) by detailing safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and explaining how to interpret them. It discloses that most pre-mapped topics may return warnings, setting realistic expectations. This level of detail is exceptional for behavioral transparency.

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 (purpose, modes, response, safety fields). It is somewhat lengthy but front-loaded with essential information. Every sentence adds meaning, though minor trimming could improve conciseness without losing content.

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

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

Given the lack of an output schema, the description explains the response structure (leg-by-leg prices, matched spreads, top_spreads_pp) and key safety fields. It covers temporal alignment and skipped comparisons, which are critical for interpreting results. A more detailed explanation of the exact response JSON keys would improve completeness, but it is already thorough.

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

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

Although schema coverage is 100%, the description adds significant value by explaining the two modes and how parameters interact (e.g., topic auto-fetches events, explicit parameters override). It also provides examples of topic values. This clarifies parameter usage beyond the basic 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's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It provides specific verb-resource and describes two distinct modes (topic shortcuts and explicit tickers), making the functionality unambiguous. The purpose is distinct from sibling tools like 'polymarket_arbitrage' or 'polymarket_edges' which focus on single-venue or other cross-venue comparisons.

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: the `topic` mode for 10 pre-mapped macro shortcuts, and explicit parameters for custom pairings. It also provides guidance on interpreting results, including warnings about compatibility and temporal alignment. However, it does not explicitly contrast with alternative tools (e.g., when to use this vs. 'polymarket_arbitrage'), which would improve clarity.

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 transparency by explaining the dual behavior (retrieve vs list all), scoping to identifier, and the relationship with remember/forget. No contradictions.

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

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

The description is concise, front-loaded with the core behavior, and every sentence serves a purpose: stating the action, listing usage context, explaining scoping, and referencing companion tools. 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 has a single optional parameter, no output schema, and annotations provide safety info, the description fully covers how to use it (retrieve or list), what it returns (values or keys), and its scope. It is complete for this simple tool.

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

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

The input schema has 100% coverage with a clear description for the key parameter. The description repeats this and adds use case examples, which is helpful but not essential beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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 retrieves a saved value or lists all keys, explicitly names companion tools (remember, forget), and gives concrete examples of stored context (ticker, address, notes). This differentiates it well from siblings like '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: 'to look up context the agent stored earlier without re-deriving it from scratch.' It implies not to use for saving or deleting by referencing 'remember' and 'forget' as companion tools. While it doesn't explicitly state exclusions, the context is clear enough.

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

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

Description contradicts annotation readOnlyHint=true by stating mark_read:true flags events as read, implying state mutation. This inconsistency is a serious flaw, reducing transparency despite other 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?

Three concise sentences with front-loaded purpose, followed by field details, filtering guidance, and alternative access. No fluff, every sentence provides value.

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

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

For a tool with no output schema, description explains returned fields (source, citation_uri, raw event payload), filtering options, read state management, and alternative access method. Sufficient for correct 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. Description adds value by providing concrete examples (e.g., 'sec_8k' for type) and behavioral context (mark_read affects future calls), warranting a 4.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools (e.g., list_subscriptions, subscribe) as no other tool retrieves alert events.

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

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

Provides clear usage context: filtering by type and since, mark_read behavior, polling suitability, and alternative GET endpoint. Lacks explicit when-not-to-use or exclusion conditions, but overall 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?

Adds significant context beyond annotations: fans out to multiple sources (SEC, GDELT/GNews, USPTO), explains fallback and failure modes, and describes return structure (grouped changes, total count, 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?

The description is a single paragraph but well-packed with examples and logic. It is slightly lengthy but every sentence contributes necessary information. Could be broken into clearer sections, but still effective.

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

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

Despite lacking an output schema, the description fully explains what the tool returns (changes grouped by source, total count, citation URIs). It covers parameters, fallbacks, and references sibling tool for alternative use. Very complete for a complex multi-source tool.

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

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

Schema coverage is 100%, but description adds value by clarifying valid `since` formats (e.g., '30d', '1y') and acceptable `value` forms (ticker or CIK). Provides usage examples that aid 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 uses specific verbs and resources ('change feed for a company') and provides example queries. It clearly distinguishes from sibling `entity_profile` which is for static profile, so an agent can select the right tool.

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

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

Explicitly states when to use this tool (e.g., 'what's new with X') and when to use the alternative `entity_profile` instead. Also describes fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail until reactivated).

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=false and idempotentHint=true. The description adds valuable behavioral details: key-value scoping by identifier, persistence differences for authenticated vs anonymous users, and 24-hour retention. 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 four sentences long, with each sentence serving a clear purpose: purpose, usage, technical detail, and pairing. No redundant or extraneous information.

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

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

Given the tool's simplicity, no output schema, and rich annotations, the description adequately covers what the tool does, when to use it, and how it behaves. Minor missing detail: behavior on overwriting existing keys, but that is implied by idempotent hint.

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

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

Schema description coverage is 100%, so the schema already explains both parameters. The description adds context about key-value scoping but does not enhance parameter meaning beyond the schema's examples.

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

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

The description clearly states the tool saves data for later reuse. It uses specific verbs and resources ('Save data') and distinguishes from sibling tools like recall and forget, which are mentioned.

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 usage context: 'Use when you discover something worth carrying forward.' It mentions pairing with recall and forget but does not include explicit when-not-to-use or alternative tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing that each call cascades through several internal lookups, which helps set expectations about latency or reliability.

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

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

The description is front-loaded with purpose and examples, but it is slightly verbose. Every sentence adds value, though the list of supported types could be more compact.

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 (two entity types, multiple input formats for company), the description covers essential aspects including return values and citation URIs. No output schema exists, so the description compensates adequately.

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

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

Schema coverage is 100% with parameter descriptions. The description goes beyond by explaining what each entity type returns (e.g., ticker + CIK + citation for company, RxCUI + ingredient for drug) and provides concrete examples like 'ozempic'.

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: resolve user-spoken names to canonical identifiers. It provides specific examples like ticker, CIK, RxCUI and distinguishes itself from sibling tools like entity_profile and compare_entities by focusing on ID resolution.

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', giving clear context. It also mentions that it replaces 2-3 manual lookups, but does not list specific alternatives or 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, openWorldHint, idempotentHint, and destructiveHint false. The description aligns by stating it probes with ai_visibility_check and returns ranked results, with no mention of side effects. It adds detail on output format (score, confidence, signal density) 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 with no redundancy. The main action is front-loaded, and every sentence adds value: purpose, method, use case, output description.

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 covers output format (ranked list with score, confidence, signal density). Parameters are fully described via schema and description. The tool complexity is moderate, and the description provides sufficient information for an agent to use it 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. The description adds context beyond schema: it notes the first entity is treated as the 'subject' for narrative and explains the purpose of context parameter for disambiguation. This adds meaningful guidance.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from siblings 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?

The description provides a clear use case: competitive AI-marketing audits, with an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or call out alternatives, though the sibling list is available.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction.

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

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

Description is detailed but each sentence adds value, covering return fields, behavior, and ecosystem limits. Slightly long but well-structured with key info upfront.

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

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

Despite no output schema, description fully compensates by listing return fields (summary block, per-advisory detail, links, alternative versions) and explaining partial failure and ecosystem scope.

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%. Description adds example of scoped packages and default version behavior but does not significantly enhance beyond schema.

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

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

The description clearly states it is a composite check for npm packages, listing specific checks (license, advisories, version history, bundle size) and explicitly distinguishing it from sibling tools by focusing on npm dependency evaluation.

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 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes NPM only in v1, providing clear when-to-use and limitations.

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, destructiveHint), the description adds critical details: the embedding model used (BGE-base-en), windowing strategy (500-char overlapping windows), character limit (200K chars with truncation flag), and that results include offsets for verification. This fully discloses tool behavior.

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

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

Three well-structured sentences: first defines purpose, second explains when and benefits, third provides technical details. Every sentence adds value, no redundancy, and information is front-loaded.

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

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

Despite lacking an output schema, the description completely explains return values (top-N passages with offsets and similarity scores). It also covers the embedding approach, window size, and character limit, leaving no ambiguity about what the tool produces.

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

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

The input schema already has 100% coverage for parameter descriptions, but the description adds practical examples for the query parameter (e.g., 'supply-chain risk') and clarifies the text parameter's max size (200K chars) and limit's default (5) and range (1-20), providing added meaning beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs and resource context. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining how they pair together, making its unique 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?

Explicitly states when to use: when the record is too large for the prompt. It also explains benefits (saves context, returns only relevant passages) and points to a complementary sibling (ask_pipeworx_grounded), providing clear guidance on tool selection.

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 implies each call creates a new subscription, but annotations set idempotentHint=true, suggesting idempotency (repeated identical calls have same effect). This is a contradiction, as creating a subscription is typically non-idempotent unless there is deduplication logic, which is not mentioned. Therefore transparency score is 1.

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 bullet points for types and delivery, front-loading the core purpose. It is somewhat lengthy but each section adds necessary context. Could be slightly more concise, but overall efficient.

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

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

Given no output schema, the description mentions return value (subscription id). It covers prerequisites, types, delivery options, and constraints (e.g., 10/day SMS cap, webhook auto-disable). It is complete for a creation 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?

Despite 100% schema coverage, the description adds significant value beyond the schema by explaining type-specific parameters (e.g., items codes for sec_8k, topics for polymarket_edge) and delivery channel details (limits, verification, auto-disable for webhook). This enriches the agent's understanding.

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

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

The description clearly states the verb ('Create'), resource ('proactive monitoring subscription'), and output ('returns the new subscription id'). It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation. Specific types and their parameters are provided.

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 (monitoring live-data event streams), prerequisites (Pipeworx OAuth account), and supported types with examples. It lacks explicit 'when not to use' but provides context via delivery channel limits and alternatives are implied by sibling tools.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds value by explaining the tool's role as onboarding, what it returns, and how to invoke. 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, front-loaded with user questions, then description of output, then usage. Every sentence earns its place, though slight repetition of categories between description and schema.

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

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

Given the tool's simplicity (one optional parameter, rich annotations), the description fully covers its purpose, usage, and place in the ecosystem. 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 has 100% coverage with parameter description. Description adds extra context about the live catalog and results shape, plus repeats the omit-for-spread guidance, slightly enhancing 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 category-bucketed example questions with tool+argument shapes. It distinguishes itself as the onboarding entry point, using specific verbs and resources.

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 instructions: use this first when unsure, call with no args for full spread, or pass topic to focus. Lists topic options. Lacks explicit 'when not to use' but overall 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?

The description adds significant behavioral context beyond annotations: ownership enforcement (security) and deactivation vs deletion (data lifecycle). Annotations already indicate non-destructive and idempotent behavior, and the description complements these well without contradiction.

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

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

Two sentences, zero wasted words. The most critical information (action, ownership, deactivation behavior) is front-loaded and efficiently presented.

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 only one required parameter and no output schema, the description is fully complete. It covers purpose, ownership, side effects (deactivation), and source of the parameter ID. No missing pieces.

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 does not add meaning beyond the parameter's schema description. However, it does mention the parameter is 'returned by subscribe', providing minimal contextual linkage. 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 action ('cancel a subscription') and the resource ('by id'). It distinguishes from sibling tools like 'subscribe', and adds specific context about ownership enforcement and deactivation, making the purpose unmistakable.

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

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

The description explicitly says when to use the tool (to cancel your own subscription) and what limitations apply (ownership enforced, deactivation not deletion). It does not explicitly mention alternatives, but the context of sibling tools provides sufficient differentiation.

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) indicate safe, non-destructive operation. The description adds significant behavioral context: returns a verdict with five possible values, extracted structured form, actual value with citation, percent delta, and replaces multiple sequential calls. No contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and examples, clearly explaining purpose, usage, scope, and output. While a bit long, every sentence adds value; it is well-structured and not overly verbose.

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 only one parameter, no output schema, and rich annotations, the description fully covers what an agent needs: when to use, what claims are supported, the return format (verdict types, citation), and efficiency gains. No gaps.

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

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

Schema covers the single 'claim' parameter with description. The description adds examples and clarifies it's natural-language, which is helpful. Given 100% schema coverage, baseline is 3; the extra examples and scope information justify a 4.

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

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

The description uses explicit trigger phrases (e.g., 'Is it true that…', 'fact check') and identifies a specific verb+resource: natural-language claim verification against authoritative sources. It differentiates from sibling tools by stating it replaces multiple sequential calls and focuses on financial claims for US public companies.

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 the agent needs to check whether something a user said is factually correct.' It also defines the current scope (company-financial claims for public US companies), implicitly indicating when not to use (other domains). Could improve with explicit alternatives for non-financial claims.

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