Foodish

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: probes LLMs, scores visibility, requires API key for Anthropic with cost implication, and details the return structure ({score, confidence, signals, raw_response}). No contradictions; full 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?

A single well-structured paragraph that front-loads the main action, then covers parameters and use cases. Every sentence adds value with no redundancy or filler. Appropriate length for the tool's complexity.

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

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

Despite no output schema, the description fully explains return values (per-model fields + combined view). It covers required and optional parameters, default behavior, prerequisites (_apiKey for Anthropic), and use cases. Complete for an agent to invoke correctly.

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

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

Schema cover all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by explaining default model behavior, how _apiKey is used (passed directly to Anthropic), and how context disambiguates. This goes beyond the schema's individual field 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 states a specific verb ('Probe') and resource ('LLMs'), defines the output ('score visibility 0-100 per model'), and lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). It clearly distinguishes from siblings by focusing on LLM visibility scoring for any entity, unlike sibling tools like 'resolve_entity' or 'deep_research'.

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

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

The description provides clear context for when to use the tool (e.g., brand checks, competitive monitoring) and explains parameter choices (default model, optional Anthropic). However, it does not explicitly state when not to use it or compare it to alternative sibling tools, leaving some ambiguity 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?

Beyond the readOnly/idempotent annotations, the description reveals it fills arguments automatically, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. It also discloses that breaking-news queries route to live news and *-news-feeds packs, adding genuine behavioral context.

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

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

Long but densely informative: the priority directive is front-loaded, followed by scope, behavior, examples, and alternative routing. Each section earns its place, though a few phrases ('START HERE', 'PREFER OVER WEB SEARCH') repeat the same core message.

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 as a meta-router with no output schema, the description covers everything an agent needs: what to ask, how the tool behaves, what the response looks like, when to prefer alternatives, and access info. It leaves no critical call-decision ambiguity.

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 the 'question' parameter and all aliases fully documented. The description adds example queries but those reinforce usage guidance rather than parameter semantics. Baseline 3 is appropriate since the schema carries the parameter-information load.

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 exactly what the tool does: it routes factual questions to 5,724 tools across 1,497 sources and returns structured answers with citation URIs. It clearly distinguishes itself from siblings by positioning itself as the default entry point and naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

Provides explicit usage rules: prefer over web search for factual questions, lists trigger phrases ('what is', 'look up', 'find', etc.) and gives concrete examples. Also states when to step up to alternatives (grounded for verbatim evidence, deep_research for broad questions), plus covers breaking-news routing.

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 readOnly/idempotent/openWorld, and the description adds valuable context: no candidate is currently active, it currently matches ask_pipeworx exactly, and it has no fallback because it is a fully functional router. This openly discloses the experimental nature without contradicting the annotations.

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

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

The description is moderately long but each sentence earns its place: beta status, current parity, usage instruction, and no-fallback caveat. It is front-loaded with the most important fact and could be slightly tighter, but has no filler.

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 router tool with no output schema, the description tells the agent everything needed to call it correctly: identical arguments/response shape to ask_pipeworx, current stable-equivalent behavior, and why it exists. The note that no candidate is active removes ambiguity about unpredictable 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 the schema already fully documents the lone required parameter and its five aliases. The description says arguments match ask_pipeworx but adds no parameter-specific semantics beyond what the schema provides, so the 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?

Description states it is a beta version of ask_pipeworx and a universal router, explicitly enumerating the same 5,724 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting candidate routing improvements, so a selecting agent can tell them apart.

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 it exactly like ask_pipeworx when you want the newest routing' and explains that this tool is compared against the stable router. This gives clear when-to-use guidance and names the sibling alternative explicitly.

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 reveals behavior beyond the readOnly/openWorld/idempotent annotations: it extracts answers using only the tool result, returns a structured evidence object, may explicitly refuse with enumerated reasons, and costs an extra LLM call. No contradiction with annotations exists.

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 the core distinction, then efficiently moves through behavior, output shape, use cases, and cost/alternative guidance. Every sentence carries decision-relevant 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?

Given there is no output schema, the description compensates by specifying the success shape and all refusal categories. It also covers cost, routing behavior, and when to choose the sibling, making it complete for safe 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%, and the schema already fully documents the question parameter and its aliases. The description does not add parameter-level detail, so the 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 names a specific capability — a grounded, hallucination-resistant answer mode — and clearly distinguishes it from the ungrounded ask_pipeworx sibling by emphasizing extraction solely from tool results. The verb 'answers' and the explicit result/refusal contract make the tool's 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?

It gives explicit when-to-use guidance for high-stakes, quotable, or actionable answers, and explicitly says to prefer the cheaper ask_pipeworx for casual lookups. This directly informs tool selection among siblings.

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

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

Annotations already indicate safe, idempotent read. The description adds extensive behavioral detail: fan-out logic, resolution contract, parent event extraction, news fallback, safety short-circuits, spread warnings, and cancellation rule parsing. 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 lengthy but well-structured with labeled sections for response shapes, resolver contract, etc. Front-loaded with main purpose. Could be slightly more concise, but detail is justified by 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?

No output schema, so description fully covers return structures: result.market, analysis, evidence, resolver fields, parent event, news fields. Also covers all edge cases and safety mechanisms. Complete for a complex 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 enriches parameters with practical context: market input examples, depth meaning and defaults, include_raw behavior and size implications. Adds significant value beyond schema.

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

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

The description clearly states it researches Polymarket bets in one call, specifies the input formats (slug, URL, question text), and provides examples of use cases. It distinguishes itself from sibling tools like polymarket_edges by focusing on a general research function.

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

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

Explicitly states when to use (should I bet, what does data say, is there edge) and covers blocking conditions like low-confidence or closed markets. Does not explicitly contrast with siblings, but context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context: pulls from specific external sources (SEC EDGAR/XBRL, FAERS, FDA, trials), handles off-calendar fiscal years, and returns sorted results with citation URIs. No contradictions, but could mention update frequency or rate limits.

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?

One concise paragraph packed with crucial information. Starts with user-facing example phrases for intent recognition, then summary, usage preference, per-type details, sorting behavior, and efficiency claim. 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?

Given only two parameters and no output schema, the description covers purpose, data sources, constraints, sorting, and return format (paired data + citation URIs). It also addresses edge cases like off-calendar fiscal years. Lacks detail on response structure but is sufficient for most use cases.

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

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

Schema coverage is 100% with descriptions. Description enriches each parameter: for 'type' it explains what data each variant retrieves; for 'values' it gives format examples (tickers/CIKs, drug names) and explicitly states min and max constraints. This goes well beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with examples of user intents. It specifies data sources for each type and is easily distinguishable from sibling tool 'entity_profile' which handles single entity lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides natural language examples that trigger usage. It also notes constraints (2-5 entities) and differentiates from single-entity lookups.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, but the description adds substantial context beyond them: account/paywall requirements, parallel facet decomposition, the findings packet contents, gaps[] with 'never invented', hop fields, fetchable citation_uri semantics, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. 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?

Dense but every clause earns its place. The most critical operational constraint (account requirement and fallback to ask_pipeworx) is front-loaded. The description packs purpose, alternatives, behavior, return format, and latency into one well-structured block 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 exists, so the description carries the burden of explaining return values — and it does thoroughly: findings packet fields, gaps[], contradictions[], hop, citation_uri, fetchability guarantee, and timing. Auth, fallback routing, and depth behavior are also covered. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds practical meaning: depth:'thorough' requires a paid plan, standard vs thorough behavior differences ('re-angles unanswered gaps' vs 'chases the best leads'), and expected latency per depth. These nuances help an agent select the right enum value beyond the schema text.

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?

States a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call'. Explicitly distinguishes itself from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups. An agent can clearly tell what this tool does and what it does not do.

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 and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Names the exact alternative tool and the conditions that route to it.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: it returns tools with names, descriptions, and full input schemas (with curated examples) ready to call directly. 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 concise and front-loaded with the main purpose. It includes a list of domains which adds clarity but is slightly verbose. Well-structured overall.

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 the description fully explains what is returned (top-N tools with names, descriptions, and full schemas) and that results are ready to call. Completely adequate for the tool's purpose.

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 description mentions that query accepts aliases (task, q, description, search), but this is already covered by the schema's property descriptions. Baseline of 3 is appropriate; minimal added value beyond schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains it returns top-N relevant tools with full schemas, distinguishing it from siblings as a discovery tool to call first.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance and implies when not to use (when tool is already known).

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 context on multi-source fan-out, specific returned fields, and patent limitation. 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 front-loaded with examples and structured clearly. Some redundancy (e.g., repeated ticker/CIK instruction) but overall 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?

For a complex tool with no output schema, description comprehensively lists all output fields, data sources, limitations, and fallbacks (patents, news). All necessary context is present.

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. Description reinforces value parameter formats (ticker or CIK) and adds context on name handling, providing extra clarity beyond schema.

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

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

Description clearly states the tool creates a holistic cross-source profile for US public companies, with specific examples and output list. It distinguishes from single-pack lookups and sibling tools like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and warns that names are not supported, directing to resolve_entity. Also notes patent soft-fail date.

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 context about clearing 'sensitive data' and 'stale context' beyond the annotations, which already indicate destructiveHint=true. 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 efficient sentences, no waste, front-loaded with the core function.

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

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

Given the simple nature (one param, no output schema), the description fully equips an agent to use the tool 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 the single parameter 'key' fully described in schema. The description adds no new parameter meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying a specific verb (delete) and resource (memory), distinguishing it from sibling tools like remember and recall.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clearing sensitive data) and direct pairing with sibling tools (remember, recall).

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

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

Annotations provide read-only, idempotent, non-destructive hints. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, which is valuable 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?

Single paragraph with clear front-loading of purpose, followed by details and use cases. Every sentence adds value; no fluff.

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

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

Despite no output schema, description explains output format (single text blob ready for site-root/llms.txt). Covers input parameters and use cases completely for a 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?

Schema coverage is 100%, so baseline applies. Description mentions URL and max_links but does not add significant meaning beyond what the schema provides.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the target users (AI crawlers) and the output format. It distinguishes from sibling tools by focusing on a specific task.

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 use cases (getting client's site indexed, drafting own project, auditing competitor). Lacks explicit when-not-to-use, but the narrow scope 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns specific fields and defaults to active subscriptions, which is helpful but not additional behavioral disclosure beyond annotations.

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

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

Two sentences: first states purpose and return fields, second provides usage guidance. No wasted words; 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?

For a simple list tool with one optional parameter and no output schema, the description fully explains what it returns and how to use it. 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% with parameter include_inactive described. Description adds context that listing is for active subscriptions by default, reinforcing the parameter's purpose.

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 uses specific verb 'List' with resource 'subscriptions', specifies returned fields (id, type, params, etc.), and distinguishes from sibling tools like subscribe/unsubscribe by focusing on viewing.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Does not mention when not to use or alternatives, but context is clear.

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

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

With all annotations false, the description carries full responsibility for behavioral disclosure and exceeds expectations. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), quota independence ('Free; doesn't count against your tool-call quota'), and a content caution ('don't paste the end-user's prompt').

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

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

The description is dense but every sentence earns its place: purpose, use cases, exclusion, guidance, workflow, and constraints. It front-loads the core action and then layers structured detail 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 feedback tool with no output schema and all-false annotations, the description covers all essential context: what triggers feedback, what distinguishes this tool from siblings, what information to include, how the claim_token follow-up works, and operational limits. No critical 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%, earning a baseline of 3. The description adds meaningful semantics beyond the schema by explaining the claim_token lifecycle and the expected referential context ('Describe the issue in terms of Pipeworx tools/packs'), which reinforces how to populate the context and message parameters.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from siblings by scoping it to 'ONLY for tools served by this Pipeworx connection' and contrasting with other MCP servers' connectors.

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 cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion ('if the tool came from a different MCP server... file it with that server instead') and a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists.').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral info: self-aggregating signal, no PII, caching behavior (5min-1h). No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the core functionality. Every sentence adds value; no redundant or filler content.

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

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

Given one optional parameter (with enum) and no output schema, the description fully covers the input semantics and expected output (top tools, packs, volume). 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% with enumerated values. The description adds semantic guidance beyond the schema by explaining that shorter windows surface hot trends and longer windows show steady-state demand.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('returns') and resources, and distinguishes itself from siblings like 'discover_tools' by focusing on what agents are calling.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use cases). While it doesn't mention when not to use or alternatives, the use cases provide strong 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: how scans work, partition filter, semantic anchor for cross-event pairs, fill check details, and response structure. 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?

Although lengthy, the description is well-structured with clear sections and front-loaded purpose. Every sentence adds value, but some internal details (e.g., 'skipped_low_similarity surfaces...') could be slightly condensed without losing meaning.

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

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

For a complex tool with no output schema, the description comprehensively covers response fields, edge cases (low similarity, placeholders), fill check, and references to sibling tool for custom sizing. It provides a complete understanding of tool 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% with descriptions for both parameters. The description adds significant meaning beyond schema: examples of event slugs, seed questions, explanation of internal processing (e.g., 'walks child markets', 'flattens markets'). Baseline 3 exceeded.

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

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

The description uses a specific verb ('Find arbitrage opportunities') and resource ('on Polymarket') with clear methodology ('monotonicity violations + partition-sum checks'). It distinguishes three modes (no args, event, topic) and their behaviors, differentiating it from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Includes recommendations, alternatives (cross-event catches patterns single-event misses), and a note on when not to trade based on fill check.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond by detailing the three model families, edge calculation, tradeable-edge knobs, and caching behavior. This comprehensive disclosure of internal logic and edge cases (e.g., Fed bets note) adds significant transparency 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 very long (over 600 words) and dense, covering models, response format, knobs, and diagnostics. While front-loaded with a clear purpose, the extensive detail on model families and caching may overwhelm agents. It could be more concise by reducing model internals and highlighting key points for selection.

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 9 parameters, no output schema, and intricate internal logic, the description is remarkably complete. It explains the three segments, edge metrics, tradeable-edge knobs, response top-level with diagnostics, and caching. The agent has enough information to understand what the tool returns and how knobs affect results.

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 minimal extra meaning for parameters beyond the schema, focusing more on output structure and internal models. For example, min_partition_leg_kelly gets a bit more context about basket trades, but overall the schema descriptions are already thorough.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and positions it as a discovery tool for 'what should I bet on today'. This distinct purpose differentiates it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on perspective clashes rather than tracking or pure arbitrage.

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 it is for discovering opportunities without paging markets, providing clear context. However, it does not explicitly list when not to use this tool versus alternatives like polymarket_arbitrage, though the sibling list implies other specialized tools exist. The detail about cached data and diagnosis for empty segments helps guide appropriate use.

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

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

Adds significant context beyond annotations: snapshots, trend computation, expired opportunities, limits (60-day TTL, daily closes). 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?

Front-loaded with purpose, detailed but dense. Every sentence adds value, though slightly verbose for a tool 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?

With no output schema, description fully details return fields (tracked, expired, snapshot_dates) with field explanations. Covers all necessary context.

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

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

Schema covers both parameters (100% coverage). Description adds default values, clamp ranges, and meaning of 'window' as snapshot family, which complements the schema.

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

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

Clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity, distinguishing it from raw edge data tools like polymarket_edges.

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

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

Implies when to use (to understand edge history versus raw snapshot) and contrasts fresh vs old edges, but lacks explicit alternatives or 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specifics: walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; basket returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, 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?

Description is long but well-structured: core function, required parameters, mode explanations with clear bullet points, and warnings. Every sentence adds value; slight redundancy but justified by 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 4 params, no output schema, and tool complexity, the description covers input modes, parameter semantics, return fields for both modes, and practical usage warnings (dominant loss mode). Completes the picture without 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 coverage is 100% (baseline 3). Description adds meaning: explains size_usd interpretation for single-market vs basket (max spend vs target proceeds vs settlement notional) and side defaults/auto mode. Adds value beyond schema descriptions.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It complements sibling tools like polymarket_arbitrage and polymarket_edges by providing a risk check before 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?

Explicitly advises using this tool before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above $500. Explains why: theoretical overround on thin books is not capturable and partial fills lead to directional risk.

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

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

The description goes far beyond the annotations by disclosing compatibility warnings, non-equivalent bet shapes, gross-vs-net fees, unverified pairings, skipped comparison counters, and the meaning of null temporal alignment. Annotations already mark the tool as read-only and non-destructive, and the description adds substantial behavioral context without contradicting them.

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

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

The description is long, but nearly every sentence carries essential warnings or behavioral disclosures for a complex cross-venue comparison tool. It is structured around modes, response fields, and safety fields, though lighter formatting would improve scannability.

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

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

Given the tool has no output schema and handles nuanced matching, fee, and safety concerns, the description is remarkably complete. It covers response fields, compatibility codes, skipped pairs, temporal alignment semantics, fee disclosure, and both invocation modes, so an agent has enough context to call 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% and the schema already documents each parameter. The description adds valuable behavior beyond the schema by explaining that topic auto-fetches matched events and that explicit ticker/slug pairings run the same matcher, which clarifies how the parameters interact.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, naming specific resources in both modes. It is specific and informative, but it does not explicitly differentiate this tool from closely related siblings like polymarket_arbitrage.

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: two modes for either pre-mapped topics or explicit event identifiers, and guidance that equivalence of bet shapes matters. It warns that pre-mapped topics are not automatically tradeable, but it does not name alternatives or explicitly state when to prefer a sibling 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context about the data source (Foodish API) and return type (image URL), which is useful 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?

Single sentence, direct, and efficient. Every part is meaningful and no redundant information.

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

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

Given no parameters, presence of output schema, and rich annotations, the description is complete. It explains the source, return type, and scope (any category).

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?

There are no parameters, so schema coverage is 100%. The description does not need to add parameter info; the baseline of 4 applies as it adds no value beyond schema but is not required.

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 a random food dish image URL from the Foodish API, specifying the categories (biryani, burger, pizza, etc.). This differentiates it from sibling tool 'random_by_category' which likely filters by category.

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 indicates it is a general random pick from any category, but does not explicitly state when not to use it or mention alternatives. However, the context of sibling tools implies 'random_by_category' for filtered 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 states the tool returns a 'random' image URL, implying non-deterministic results. This directly contradicts the annotation 'idempotentHint: true', which indicates the tool should be idempotent (same input yields same output). This is a clear annotation contradiction.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and valid categories. Every word adds value with no redundancy or unnecessary detail.

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 low complexity (one parameter with enum, output schema exists, strong annotations), the description is complete: it states the action, input, output (URL), and valid values. The annotations cover safety and idempotency (despite the contradiction in behavior), and the description adds the remaining context.

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

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

The description lists valid categories, but this merely repeats the enum values already in the input schema. Since schema coverage is 0%, the description should add new meaning, but it does not. It provides no additional context about the parameter's format, constraints, or behavior.

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 'Return' and the resource 'random food image URL for a specific category', distinguishing it from sibling 'random' which likely returns non-category-specific results. The list of valid categories further clarifies scope.

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

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

The description explicitly says 'for a specific category' and lists valid categories, giving clear usage context. However, it does not mention when not to use this tool or compare with alternatives like the sibling 'random' 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 indicate read-only, non-destructive, idempotent. Description adds scoping detail (identifier-based) and that it retrieves or lists, consistent with annotations. 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?

Three sentences, no fluff. First sentence defines action, second gives context, third adds scoping and related tools. Efficient and 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?

Covers purpose, usage, scoping, and relation to siblings. Lacks details on return format or error handling, but acceptable for a simple retrieval 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%, but description clarifies that omitting key lists all saved keys, adding meaning beyond the schema description.

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

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

Description clearly states the tool retrieves saved values (via remember) or lists keys, with specific verb (retrieve/list) and resource (saved values). Distinguishes 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?

Provides explicit use case: look up previously stored context without re-deriving. Mentions scoping and pairing with remember/forget, but no explicit when-not-to-use or alternatives.

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

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

Description discloses that mark_read:true modifies state (flags events read), contradicting the readOnlyHint annotation which claims no state modification. Per scoring rules, contradiction yields a score of 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?

Four sentences, front-loaded purpose, each sentence adds value (return payload, filtering, mark_read, polling alternative); no fluff.

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

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

For a simple retrieval tool with no output schema, description explains return fields, all parameters, polling suitability, and alternative endpoint; no gaps detected.

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 useful context for mark_read ('so next call only shows newer ones') and type example ('sec_8k'), providing 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?

Clearly states 'Pull fired events from your subscription feed' and lists returned fields and filtering options, distinguishing it from sibling tools like list_subscriptions.

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

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

Provides explicit guidance on filtering by type and since, using mark_read for read tracking, and notes polling suitability; lacks explicit when-not-to-use or alternative tool suggestions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: sources (SEC, GDELT, GNews, USPTO), fallback behavior, failure modes, and return structure (changes grouped by source, total_changes, 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?

Single paragraph is dense but well-organized: starts with examples, core purpose, source details, parameter format, return structure, and alternative. Every sentence adds value, though could be more structured (e.g., bullets) for easier scanning.

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

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

Given 3 params, no output schema, the description covers all essential aspects: query examples, source behavior, failure modes, output shape, and when to use alternative. Complete for the tool's complexity.

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

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

Schema coverage is 100% with parameter descriptions, baseline 3. Description enhances with examples of 'since' formats and acceptable 'value' types, adding clarity 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 provides a change feed for a company over a time window, aggregating multiple sources. It distinguishes from sibling 'entity_profile' explicitly with examples of queries it handles.

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?

Numerous query examples illustrate when to use. Explicitly directs to use 'entity_profile' for static profiles, providing clear guidance on 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 provide idempotent and destructive hints. Description adds value by explaining scoping by identifier, persistence duration (24 hours for anonymous, persistent for authenticated), and pairing behavior. 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?

Four sentences, front-loaded with purpose, followed by usage and details. No superfluous text. 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?

Covers purpose, usage, persistence, and sibling relationships. Lacks explicit mention of overwrite behavior, but idempotent hint implies safe retry. Adequate for a write-only tool with 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 covers both parameters with descriptions, and description adds usage context and examples (e.g., subject_property, target_ticker). With 100% schema coverage, description enhances 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?

Description clearly states the tool saves data for reuse later, specifies it's for cross-session or cross-conversation storage, and distinguishes from siblings recall and forget by naming them explicitly.

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

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

Explicitly describes when to use (discovering something worth carrying forward) with examples, and mentions persistence details. Lacks explicit when-not guidance, but pairing with siblings provides context.

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

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

Annotations already mark readOnly, idempotent, and non-destructive, but the description adds critical behaviors: internal cascade across multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit handling of ambiguous matches (returns figi_candidates), and explicit `unresolved` field for failed lookups. This goes far beyond annotation hints.

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

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

The description is long but every sentence earns its place. It's front-loaded with the core purpose and 'Use FIRST', then organized into SUPPORTED TYPES with clear subpoints. The length is justified by the tool's complexity, and the structure guides the reader from generalized use to specific edge cases 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 tool with no output schema and 2 parameters, the description is remarkably complete: it explains the return concept (canonical identifiers, unresolved field, figi_candidates), covers all supported entity types, details resolution fallbacks, and even warns about input pitfalls. An agent has everything needed to call it correctly in most scenarios.

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

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

Schema coverage is 100% for both parameters, but the description elevates meaning: it explains the `value` parameter's exact formatting rules, warns against including trailing security-class words for bonds, and clarifies how ticker/CIK/ISIN inputs resolve. For `type`, it details what each enum value returns, including the ISIN-to-LEI mapping for non-US issuers. This is substantial added 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 is crystal clear: it states the core action ('resolve a user-spoken NAME to the canonical/official identifiers'), gives multiple query examples, and enumerates supported types with specific identifier sources. It distinguishes itself from siblings like entity_profile and compare_entities by focusing on ID resolution as a prerequisite.

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 directive 'Use FIRST whenever you have a name but need an ID' provides unambiguous when-to-use. It also spells out edge cases (bonds, non-equity instruments, ambiguous matches) and what to pass vs. what not to pass. While it doesn't name alternative tools, the primary use condition is so specific that an agent is unlikely to misapply it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by explaining the internal behavior of probing each entity and returning a ranked list with specific fields.

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 clear sentences plus a parenthetical example. Front-loaded with the main action. Efficient without being overly brief.

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 compensates by listing return fields (score, confidence, signal density). The 4 parameters and their roles are adequately covered.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context about the first entity being treated as the subject, which is not in the schema, and explains the probe process.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, with specific actions: probe with ai_visibility_check, rank by score, surface most/least recognized. Distinguishes from the sibling ai_visibility_check by being multi-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?

Provides an explicit use case (competitive AI-marketing audits) with an example question. Implies when not to use (single entity check) but does not mention alternatives like compare_entities.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds valuable context: fans out across services, returns specific fields, and documents partial failure ('bundlephobia's first measurement... can take 5-30s; sources_failed will list it'). 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 a single dense sentence that front-loads purpose and includes many details. While information-rich, it could be slightly restructured into multiple sentences for 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, description thoroughly explains return value: summary block with specific fields, per-advisory detail, links, alternative versions, and sources_failed for partial failures. No gaps for a tool with two 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% with descriptions for both parameters. Description adds that version defaults to latest when omitted and scoped packages are accepted, 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?

Description specifies verb 'scan', resource 'dependency', and clearly states it's a composite check for npm package safety, popularity, and size using deps.dev and bundlephobia. It distinguishes from siblings by noting 'NPM ecosystem only' and referencing deps.dev:version for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides alternative for other ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char sliding windows, 200K char cap, truncation flag. Discloses return fields (passages, offsets, similarity scores) and verification benefit.

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 use case, followed by technical details. Every sentence adds value—no redundancy. Appropriate length for 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?

Given the tool's complexity (semantic search, offsets, pairing), the description is complete. No output schema exists, but the description adequately describes return format (passages, offsets, similarity scores).

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

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

Schema coverage is 100% with good descriptions. The description adds value by providing natural-language query examples, explaining the text parameter further, and specifying limit default and range. No additional param details 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 clearly states it performs semantic search inside a fetched record, with a specific use case (large records) and explicit contrast to sibling ask_pipeworx_grounded. Verb 'search' + resource 'a fetched record' is unambiguous.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative pairing with ask_pipeworx_grounded. Also mentions truncation at 200K chars.

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 important behaviors beyond annotations: returns new subscription id, delivery options with per-event limits (10/day SMS), webhook HMAC signing, and auto-disable after 10 consecutive failures. No contradictions with annotations (idempotentHint=true is consistent).

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

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

Front-loaded with core purpose and requirements. Each sentence adds value, though the delivery section could be slightly more concise. Still, no wasted words and 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?

For a tool with no output schema, the description covers prerequisites, return value, all type-specific params, delivery options, constraints (phone verification, daily cap), and error handling (auto-disable). Complete and actionable for an agent.

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

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

Schema coverage is 100% and the description adds significant value with type-specific examples (e.g., sec_8k items codes, polymarket_edge topic, delivery webhook signing secret). This far exceeds the baseline of 3.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This verb+resource combination is specific and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly requires a Pipeworx OAuth account and notes anonymous/BYO cannot persist subscriptions. It also details supported types and delivery channels, implying when to use each. However, it does not explicitly state when not to use this tool in favor of alternatives like the feed pull.

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 true. Description adds context: returns examples with tool+argument shapes, drawn from live catalog, non-destructive. No contradiction.

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

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

Front-loaded with example query phrases, then explains behavior and parameter use. Slightly long but every sentence adds value; well-structured for 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?

Covers all relevant aspects: what it returns, how to use, parameter details, and recommended usage scenario. No output schema but return format is described 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 one parameter. Description enriches by listing example topics ('finance', 'pharma', etc.) and clarifying omission gives full spread, adding 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 specifies it is an onboarding entry point returning category-bucketed example questions with tool+argument shapes, and explicitly distinguishes from siblings like ask_pipeworx and discover_tools by advising use 'FIRST when you do not yet know what Pipeworx can do'.

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 it (first, for onboarding) and how to call (no args or with topic). Does not explicitly mention when not to use, but the context of siblings implies alternatives.

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

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

Annotations already provide idempotent and non-destructive hints. Description adds key behavioral details: ownership enforcement and that rows are deactivated not deleted, linking to recent_alerts for historical access.

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, direct and front-loaded. No wasted words; every sentence adds value.

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

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

Tool is simple (1 param, no output schema). Description covers purpose, ownership, and behavioral effects adequately for 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% with 'id' description already clear. Description repeats 'by id' but adds no new parameter semantics beyond schema.

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

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

Description states 'Cancel a subscription by id' with clear verb and resource. It distinguishes from siblings like subscribe and list_subscriptions by specifying cancellation and ownership enforcement.

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?

States when to use: cancel subscription by id. Mentions ownership enforcement (can only cancel own subscriptions), implying not for others. Could add explicit alternatives but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive behavior, and the description adds substantial context beyond that: the SEC EDGAR fast path, the grounded pipeline, verbatim evidence, and especially the critical caveat that could_not_verify means the check did not happen and must not be treated as evidence. This is exactly the kind of behavioral nuance agents need.

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 longer than average but every sentence earns its place: trigger phrases, when-to-use, routing, return value, and error semantics. It is front-loaded with purpose and structured logically. Slightly dense, but not wasteful.

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

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

Despite no output schema, the description fully explains the return verdicts, the actual value with citation, reasoning, and the meaningful distinction between could_not_verify and unsupported. It covers the tool's complexity and edge cases thoroughly, making it self-sufficient for an agent.

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

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

Schema coverage is 100% and the schema already describes both parameters well. The description adds extra meaning for tolerance_pct by explaining it overrides the claim-wording implied tolerance and recommending 1–2 for hallucination detection. This exceeds the baseline 3 for fully covered schemas.

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 a specific verb (verify/check) against a clear resource (natural-language factual claims) and enumerates trigger phrases. It also distinguishes company-financial claims (SEC EDGAR/XBRL fast path) from all other factual claims, which differentiates it from sibling research/ask tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the routing behavior for company-financial vs. other claims and mentions it replaces 4–6 sequential calls. However, it does not name specific alternative tools or state when not to use it, so it stops short of a full 5.

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