Performance Review

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

Annotations already mark it as read-only, idempotent, non-destructive. Description adds that default model is free and Anthropic requires BYO key with direct payment. 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, front-loaded with action and output. Every sentence adds value: what it does, default behavior, example uses. No wasted words.

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

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

No output schema, but description fully covers return structure (per-model score, confidence, signals, raw_response + combined view). Also explains prerequisite (API key) and use cases. Adequate for complexity.

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

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

Schema covers all 4 parameters (100% coverage). Description adds beyond schema: explains default model for 'models', that '_apiKey' is for Anthropic, and 'context' disambiguates entities. Value-add over baseline 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 it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. Distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on scoring and multi-model probing.

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

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

Lists explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not mention when not to use or alternatives, but context is clear enough.

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

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

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds behavioral context: the tool acts as a router, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. This goes beyond the annotations and helps set expectations, though it does not detail failure or error behavior.

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

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

The description is long but well-structured: it front-loads the most important use case, then provides a concise trigger-phrase list, examples, and routing alternatives. Every part contributes to correct tool selection, though the example list is somewhat exhaustive and could be trimmed.

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

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

There is no output schema, but the description compensates by stating that answers are structured and include stable citation URIs. It covers the tool's scope, input, alternatives, and broad behavior well. The main missing piece is a clearer picture of how the output is structured or what happens with unsupported queries, but the description is still complete enough for practical use.

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

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

The input schema has 100% description coverage and clearly documents the `question` parameter and several aliases. The tool description reinforces that the input should be a natural-language query and provides helpful examples, but it does not need to add much more because the schema already captures the parameter semantics.

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

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

The description clearly states what the tool does: it routes a natural-language factual question to one of many external data sources and returns a structured answer with stable citation URIs. It also differentiates itself from sibling tools by saying 'PREFER OVER WEB SEARCH' and by directing grounded or multi-part questions to ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: use for current/historical data, 'what is', 'look up', 'get the latest', and general factual questions. It also names specific alternatives such as ask_pipeworx_grounded for single-source grounded answers and deep_research for broad/multi-part questions, making the selection clear.

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

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

Beyond the annotations, the description reveals important behavior: this is an experimental edge, candidate routing may be enabled or retired, and currently no candidate is active so behavior matches ask_pipeworx. The note that it falls back to nothing and is a full working router adds safety-relevant context not captured by 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 sized and front-loaded with the identity and purpose. The parenthetical details and current-state note earn their place, and the final clarification prevents misinterpreting 'beta' as an incomplete tool.

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

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

Given that the tool has no output schema, the description compensates by referencing the same response shape as ask_pipeworx. It explains parity, current experimental state, and routing behavior, making it complete enough for an agent to know how to invoke and what to expect.

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

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

The input schema already fully describes the parameters and aliases with 100% coverage, so the parameter arithmetic is handled. The description adds only general mention of 'same arguments' as ask_pipeworx, which is useful context but does not add 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 states a specific purpose: it is the beta version of ask_pipeworx with candidate routing improvements, and it explicitly distinguishes itself from sibling tools by noting it is 'identical' to ask_pipeworx. It also clarifies that this is not a thin wrapper or fallback but a fully working universal router.

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

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

The description gives clear context: use this when you want the newest routing, and use it exactly like ask_pipeworx. It also explains the relationship to the stable router, but it does not explicitly state when to choose ask_pipeworx over ask_pipeworx_beta or mention exclusion cases.

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

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

The description discloses crucial behavior beyond annotations: it refuses when data is insufficient—with named refusal_reason values—and it asserts content is taken only from the tool result. It also reveals the one-extra-LLM-call overhead. These are concrete reliability and cost traits an agent needs to know.

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

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

Every sentence carries distinct, high-value information: behavior, routing, extraction policy, success and refusal shapes, usage triggers, and cost trade-off. It is compact for the complexity it covers and the most important purpose wording appears first.

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

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

The description is complete for a single-parameter tool with no output schema. It fully defines success and refusal payloads, the set of refusal reasons, and the context in which the tool should be used. An agent can confidently decide whether to invoke it and interpret the result, without needing an output schema.

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

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

Schema documentation coverage is 100%, fully describing the one required parameter and its aliases. The description says 'natural language' but no new parameter meaning is added beyond the schema. Given the high schema coverage, a baseline of 3 is correct.

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 purpose: a hallucination-resistant, grounded answer mode that extracts an answer only from tool-scoped data. It clearly distinguishes itself from ask_pipeworx while acknowledging they share routing. The phrase 'grounded' plus the refusal mechanics leaves no ambiguity about what the tool does.

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 when-to-use guidance is provided: use when answers will be quoted, cited, or acted on and invention of facts is unacceptable. It contrasts with ask_pipeworx by noting the extra LLM call and saying to prefer the sibling for casual lookups. This is model decision-ready 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?

The description discloses extensive behavioral details beyond annotations: fan-out logic, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and cancellation rules. No contradictions with annotations (readOnlyHint, etc.) are present.

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

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

The description is long but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Some enumeration (e.g., classifier list) could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description thoroughly explains return values, edge cases (closed markets, low-confidence, wide spreads), cancellation rules, and evidence sources. It is 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?

With 100% schema coverage, the description adds significant context: examples for the 'market' parameter, explanation of 'depth' (quick vs thorough), and detailed rationale for 'include_raw' (when to use true/false and impact on response size).

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', specifying the verb (research) and resource (Polymarket bet). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by being a general research tool.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also describes behavior for unsuitable cases (closed markets, low-confidence matches) and includes safety notes, though it does not explicitly state when not to use or name 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?

Despite annotations indicating read-only, idempotent, non-destructive, description adds valuable behavioral details: for companies, pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, pulls FAERS counts, FDA approvals, trial counts. Also mentions sorting by primary metric and citation URIs. 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 one cohesive paragraph, front-loaded with example queries. It efficiently packs details but could benefit from slight structural separation (e.g., bullet points) for easier parsing. No wasted words, though.

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 2 parameters (both required, 100% covered), no output schema, the description fully explains input, behavior (including entity-specific logic), and output format (paired data with citation URIs). The agent has all necessary information 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 already describes parameters with 100% coverage. Description adds meaning: explains how 'type' determines which data is pulled, and that 'values' expects tickers/CIKs for company or drug names. Also clarifies constraints like min/max items.

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 identifies the tool's action: comparing 2-5 entities (companies/drugs) in a single parallel call, using specific verbs like 'compare', 'vs', 'rank'. It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison.

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

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

Explicit guidance to prefer this tool over sequential single-entity lookups when comparing entities. Provides example queries and context for when to use (comparative questions). No exclusion criteria mentioned, but clear recommendation.

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 substantial behavior beyond the readOnlyHint/openWorldHint annotations: account/plan dependencies, decomposition and parallel routing mechanics, output packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] semantics, contradiction scan, semantic excerpting of large records, and latency expectations. The description clearly complements and enriches the annotations rather than 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?

Though long, the description is front-loaded with the most important operational constraint (account/depth requirement), immediately followed by a route to an alternative. Every sentence earns its place: purpose, scope, alternatives, output shape, gap/citation semantics, and expected runtime. It is dense but each detail serves agent decision-making.

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 two parameters and no output schema, the description gives an unusually complete picture of what happens under the hood, what comes back, the citation staleness, gaps, and timing. Combined with the schema and annotations, an agent has enough to select the tool, construct a good question, and interpret results confidently.

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 explains the depth enum (quick/standard/thorough, defaults, paid flag) and question style. The description adds meaningful extra semantics by tying depth to latency (60s vs 90s) and by reinforcing the 'broad/multi-part questions' use-case for the question parameter, contributing beyond a strict schema baseline.

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

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

The description starts with a clear, action-oriented purpose: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' in one call, and explicitly contrasts itself with open-web search. It clearly distinguishes itself from sibling ask_pipeworx by saying it is for broad multi-part questions over structured data, not single lookups.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use for complex multi-faceted research across structured sources; use ask_pipeworx when not signed in or for a single lookup. It names the alternative tool and the conditions, so an agent can route correctly without guessing.

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 and idempotentHint true, destructiveHint false. The description adds behavioral details beyond annotations: returns top-N relevant tools with full schemas and curated examples, ready to call directly. 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 fairly concise but front-loaded with the core purpose. It includes a list of example domains which is helpful but could be slightly trimmed. Still well-organized and informative.

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

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

Despite no output schema, the description explains what is returned (names, descriptions, schemas with examples) and notes the limit parameter's range. For a discovery tool with high annotation coverage, this is sufficiently complete.

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

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

Schema coverage is 100%, but the description adds context by explaining that query accepts natural language descriptions like 'analyze housing market trends' and lists aliases. This enriches understanding. Slight deduction for not specifying the default limit value in the description.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains and tasks (SEC filings, FDA drugs, etc.), distinguishing this discovery tool from its siblings which are specialized 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?

Explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent precisely when to use this tool vs. others.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds non-obvious context: fans out across SEC, XBRL, USPTO, news, GLEIF; soft-fail for patents; specific return fields. Does not contradict annotations.

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

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

The description is front-loaded with example queries and is concise given the complexity. It contains no superfluous information, though slightly verbose with the list of returned items; still highly efficient.

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

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

Given the tool's complexity (multiple data sources, specific fields), the description is very complete. It explains return value structure, limitations (patent sunset, name not supported), and notes no output schema is needed. All relevant context is 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. Description further clarifies that type is only 'company' today, value must be ticker or zero-padded CIK (not names), and recommends resolve_entity for names. Adds significant meaning beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' with specific example queries. It distinguishes from sibling tools by noting it covers multiple sources in one call, unlike chaining single-pack 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?

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. Also advises using resolve_entity if only a name is given, which provides a clear alternative.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about use cases but does not elaborate on behavior beyond deletion (e.g., error handling, irreversibility).

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 two sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description explains what it does and when to use it. It is mostly complete, though it could mention idempotency or error behavior more explicitly.

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

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

Schema coverage is 100% with description 'Memory key to delete'. The tool description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the action (Delete) and resource (previously stored memory by key). It is specific and distinct from siblings like remember and recall, which are mentioned for pairing.

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

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

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It mentions pairing with remember and recall, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and idempotentHint. The description adds that it fetches the page, extracts title/description/key links, and outputs a single text blob for site-root/llms.txt. This provides useful behavioral context beyond the annotations, though no rate limits or auth details are mentioned.

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

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

Two concise sentences plus a bullet-style list for usage. Every sentence adds value, no fluff. Front-loaded with the core purpose.

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

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

Given only 2 parameters with 100% schema coverage, clear annotations, and a simple text output (no output schema), the description is fully adequate. It explains what the tool does, how it works, and what the output is.

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 documents both parameters. The description briefly explains the process (fetches page, extracts info) which adds context, but does not add new meaning to url or max_links beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and scope (any URL). It distinguishes from siblings like scan_competitor_ai_presence by focusing on the specific task of creating the file itself.

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 usage scenarios (getting a client's site indexed, drafting for own project, auditing competitor), giving clear context. It does not mention when not to use or alternative tools, but given the specific niche, this 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?

Description adds return field details beyond annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so description confirms behavior without contradiction.

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

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

Two sentences, front-loaded with purpose and usage guidance. No wasted words.

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

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

Covers purpose, returned fields, and usage context. Lacks details on ordering or pagination but sufficient for a simple list tool with good annotations.

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

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

Schema coverage is 100% with a clear description for the single parameter 'include_inactive'. Description does not add additional 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?

Clear verb 'List' specifies resource 'the caller's active subscriptions' and lists returned fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides context but no explicit exclusions for alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. Description adds that the output 'communicates nothing clearly', explaining the satirical nature. 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?

Single sentence front-loads the core purpose and all key parameters, with no wasted words. Efficient and clear.

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

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

Given output schema exists (context signal), the description's brief statement about return value is sufficient. All parameters are identified, and the tool's behavior is adequately described for its complexity.

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

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

Schema description coverage is 0%, so description must compensate. It lists all five parameters (employee_name, role, rating, actual_performance, what_manager_wants_to_say) and implies their roles through the overall purpose. The description adds context beyond the plain schema properties.

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

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

Description clearly states it generates a satirical corporate performance review, specifying the verb 'generate' and resource 'performance review'. The tool is unique among siblings; no other sibling tool generates reviews.

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

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

Description implies the tool is for generating satirical reviews but does not explicitly state when to use vs alternatives, nor provide exclusions or alternative conditions. Sibling context shows no similar tool, leaving use case implicit.

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

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

Annotations are all false, so the description carries the full burden, and it excels. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token flow (returned without an account, usable later to read status), that the team reads digests daily, and that signal affects roadmap. It also warns against pasting end-user prompts. 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 long but dense with necessary information. It is front-loaded with purpose, then covers when-to-use, scope restrictions, token mechanics, and operational details. Each sentence earns its place, though it could be tightened slightly by merging some clauses. The structure flows logically from purpose to usage to constraints.

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?

This is a complex tool with two modes (submitting feedback and reading replies via claim_token), nested objects, no output schema, and no useful annotations. The description covers both modes, the parameter relationships, rate limits, quota, and scope, making it complete for an agent to use correctly. Since there is no output schema, the description appropriately focuses on invocation semantics rather than return values.

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

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

Schema coverage is 100% and each parameter has a clear description, so the baseline is 3. The description adds meaning beyond the schema by explaining how to use claim_token with a concrete example ('pipeworx_feedback({claim_token:"pwfb_…"})') and that it must be passed with no other arguments. It also contextualizes the `message` field by saying to be specific and not paste the user's prompt. The `type` enum is well-covered by the schema, but the claim_token usage tips elevate this above baseline.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and it distinguishes the tool from sibling tools by focusing on feedback rather than research or visibility. The scope is further clarified with the exclusion of non-Pipeworx tools.

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

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

The description explicitly states when to use the tool: '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 provides clear exclusions: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for tools from other MCP servers. The 'Not sure?' clarification adds a practical heuristic.

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

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

Annotations already set readOnlyHint and idempotentHint. Description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching duration (5min-1h). 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?

Concise paragraph front-loaded with the main result, followed by use cases and technical details. Every sentence provides value with no redundancy.

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

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

No output schema, yet description clearly states what is returned (top tools, top packs, total call volume). Also covers data source, privacy, and caching. 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 coverage is 100% with a single optional parameter featuring an enum. Description reinforces the semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds context 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?

Clearly states it returns top tools, top packs, and total call volume over a window. Distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on trending usage rather than answering questions.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking alignment). Mentions caching behavior. Lacks explicit when-not-to-use but the use cases are well-defined.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, so the description doesn't repeat those. It adds extensive behavioral context: algorithms (monotonicity violations, partition-sum), Jaccard similarity threshold, partition filter, fill check, and expected output fields. No contradiction with annotations.

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

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

The description is lengthy and detailed, but structured with sections for modes, algorithms, and output. Every sentence adds value, but it could be more concise. Front-loaded with purpose, then details.

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

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

Given the tool's complexity (2 optional params, no output schema), the description is comprehensive. It explains output fields, edge cases (placeholder filter, fill check), and provides detailed reasoning for operations. It covers all key aspects needed for correct usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds further value by explaining the meaning of event slug and topic with examples, and differentiating the behavior of each mode.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, with three modes: no args (trending_scan), event, and topic. It is specific about verb and resource, but does not explicitly differentiate from sibling tools like polymarket_edges, though it hints at polymarket_fill_risk for sizing.

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

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

The description provides clear context for each parameter: no args for trending scan, event for specific market, topic for cross-event. It explains when to use each mode and why cross-event catches patterns missed by single-event. However, it does not explicitly list when not to use this tool or alternatives 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?

The description goes far beyond annotations by detailing three model families, edge calculation, caching (KV level 1h), diagnostics, and filtering knobs. It explains behavioral traits like partition kelly being zero at parent level and Fed bet exclusion. 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 long but well-structured with front-loaded purpose and clear sections. Every sentence adds value, though some detail could be condensed without losing essential 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?

Despite the tool's complexity (9 parameters, no output schema), the description thoroughly covers return structure (by_segment, fed_candidates, diagnostics), caching, model details, and behavioral traits. It is comprehensive enough for an AI agent to understand and use 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 description adds significant context to parameters: e.g., min_kelly explains skipping small opportunities, max_spread_pp warns about edge erosion, min_liquidity describes walking the book, and min_partition_leg_kelly clarifies why min_kelly doesn't filter partitions.

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 ('Scan') and resource ('top Polymarket markets') and clearly states the tool's purpose: returning opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge scanning.

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

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

The description explicitly states it is built for 'what should I bet on today' and explains that agents can discover opportunities without paging. It provides context for when to use segments and excludes Fed bets with a rationale. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds rich behavioral details: output structure, trend computation, decay formula, snapshot TTL, and data gaps. 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 dense with information but somewhat lengthy; could benefit from clearer structure. However, 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?

Given lack of output schema, description fully explains output (tracked[], expired[], snapshot_dates[]) and covers limitations, edge cases, and computational details. 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 provides parameter descriptions (100% coverage). Description adds value by specifying defaults (14, '1wk'), clamp (2-30), and effect of parameters, going beyond the schema.

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

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

Description clearly states the tool's purpose: edge persistence and decay telemetry. It answers specific questions ('how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges and bet_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?

Description explains when to use (for checking edge persistence and decay) and implies when not (e.g., for non-persistent edge data). Does not explicitly list alternatives but mentions snapshot families and limits.

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. Description adds substantial behavioral context: walks the order book ladder, returns specific fields like slippage_pp and verdict, and warns about partial fills and 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 with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Information is front-loaded. Could be slightly more concise, but organization compensates for verbosity.

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

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

Given no output schema and 4 parameters, the description provides thorough coverage: explains both modes, all return fields, usage thresholds, and risk of partial fills. It fully compensates for the lack of output schema and is complete for agent to understand 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 description coverage is 100%, so baseline is 3. Description adds value by clarifying interpretation of size_usd in basket mode (settlement notional, shares per leg) and explaining defaults for side in basket mode (auto). While schema covers the basics, description enriches parameter understanding.

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

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

Description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes two modes (single-market and basket) and lists return fields. Differentiates from sibling tools like polymarket_arbitrage and 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?

Explicitly tells when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains consequences of not using it (partial fills leading to unhedged directional risk, which is the dominant loss mode). Provides clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it explains the compatibility warning conditions (non-equivalent bet shapes, unmatched events), temporal alignment field, skipped_cross_type/subtype counters, and notes that most pre-mapped topics return warnings. No contradictions with annotations.

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

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

The description is reasonably concise given the complexity. It is front-loaded with the main purpose and modes, then details response and safety fields. Some redundancy exists (e.g., 'pre-mapped ≠ tradeable' repeats earlier warnings), but overall it is well-structured and every sentence adds value.

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

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

Given the complex cross-venue comparison with no output schema, the description is highly complete. It covers response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning conditions, temporal alignment, skipped counters), and edge cases (mismatched bet shapes, semantic unrelatedness). No gaps are apparent.

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 all three parameters described. The description adds meaning beyond the schema by explaining the two modes (topic vs explicit), how the topic parameter maps to 10 shortcuts, and that explicit parameters override the topic-mapped side. It also provides examples of parameter values.

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

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

The description uses a specific verb ('computes cross-venue spread') and clearly identifies the resource ('Kalshi and Polymarket for the same resolving question'). It differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly focusing on cross-venue spread and mentioning two distinct modes (topic shortcuts and explicit tickers).

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

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

The description explicitly states when to use the tool (for comparing prices across venues) and provides clear conditions when spreads are meaningless (temporal misalignment, non-equivalent bet shapes). It warns that most pre-mapped topics return compatibility warnings, guiding the agent to not blindly rely on the output.

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=true, destructiveHint=false, idempotentHint=true. The description adds that listing all keys occurs when key is omitted, and that it is scoped to the agent's identifier. No contradictions; the description supplements 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 clear and well-structured, with useful context. It includes a bit of extra wording ('without re-deriving it from scratch') that adds value, but could be slightly more concise.

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

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

Given one parameter, no output schema, and full schema coverage with annotations, the description is fairly complete. It covers purpose, usage, scoping, and tool pairings, leaving little 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 coverage is 100% for the single parameter 'key', with a description that matches the tool description. The description reiterates that omitting key lists all keys, but does not add significant new meaning beyond the schema.

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

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

The description clearly states that recall retrieves a value saved via remember, and that omitting the key argument lists all saved keys. The verb 'retrieve' and resource 'value' are specific, and it distinguishes itself from siblings like remember and forget.

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

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

The description explains when to use it: to look up context stored earlier without re-deriving. It also mentions scoping (anonymous IP, BYO key hash, account ID) and pairing with remember and forget. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds behavioral context by explaining the effect of 'mark_read' (flags events as read) and confirms polls are safe. No contradiction.

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

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

The description is concise with no redundancy. It front-loads the core action and returns structure, then efficiently covers filtering options and usage note. Every sentence adds value.

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

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

For a read-only tool with no output schema and simple parameters, the description is complete. It explains what is returned, filtering options, side effects of mark_read, and even provides an alternative access method. 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?

All 5 parameters have schema descriptions (100% coverage). The description adds value by giving examples (e.g., 'type' with 'sec_8k'), explaining the effect of 'mark_read' and 'unread_only', and clarifying default values like limit=50. This exceeds the baseline.

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: 'Pull fired events from your subscription feed.' It specifies what each alert carries (source, citation_uri, raw payload) and distinguishes from sibling tools by focusing on recent alerts, while siblings like 'recent_changes' and 'subscribe' have different purposes.

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 good usage context: it explains when to use (to get recent alerts), how to filter by type and since, and mentions that polling works fine. It also gives an alternative access method via a GET URL. It doesn't explicitly exclude scenarios but the guidance 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 mark as readOnly and idempotent; description adds details on data sources (SEC, GDELT, GNews, USPTO) and fallback behavior (GDELT preferred, GNews when rate-limited), with 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 thorough but slightly verbose. However, it is well-structured with example queries first, then mechanism, then return format, then sibling distinction. Could trim some 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?

Despite lacking output schema, description specifies return structure (changes[] grouped by source, total_changes count, citation URIs) and addresses edge cases (USPTO soft-fail, fallback behavior). 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 already covers all parameters with descriptions; description enriches `since` with specific examples ('7d', '30d', '3m', '1y') and clarifies value can be ticker or CIK.

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

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

Description clearly states it provides a change feed for a company in recent N days, with example queries like 'What's new with X' and explicit differentiation from sibling tool entity_profile.

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

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

Provides explicit when-to-use guidance via example queries and directly states when to use entity_profile instead. Also gives context on window formats ('30d' for typical monitoring).

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

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

Description adds value beyond annotations: scoped by agent identifier, persistence duration (24 hours vs persistent), and pairing with recall/forget. Annotations already indicate idempotent and not destructive, so description complements well.

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

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

Four sentences, front-loaded with primary purpose. Efficient but could slightly merge repetition of 'store' idea. No wasted words.

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

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

Covers scope, persistence, usage context, and companion tools. No output schema needed for this simple tool. Could mention success/failure feedback, but not required.

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. Description adds example keys ('subject_property', 'target_ticker') and elaborates on the value purpose, providing meaningful context beyond the schema.

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

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

Clear verb 'save data' with specific resource 'key-value pair'. Distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning them as companions.

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: 'when you discover something worth carrying forward... so you don't have to look it up again.' Provides context on persistence for authenticated vs anonymous users. Does not explicitly state when not to use, but context is sufficient.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral details: identifiers are labelled with source, unresolved identifiers are explicitly listed under 'unresolved', LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple lookup endpoints. This adds substantial context beyond the structured annotation 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?

The description is long but front-loaded with query examples and then dense with valuable detail. Every sentence contributes—no fluff. The structure flows from use cases to supported types to degradation behavior, making it easy to scan and digest.

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, the description fully explains what is returned: CIK, ticker, company_name, LEI, FIGI, source labels, unresolved field, RxCUI, ingredient, brand, and citation. It also covers edge cases like unavailable external services and non-US issuers. The tool's moderate complexity (2 params, 2 types) is completely addressed.

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

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

Although the schema already describes both parameters, the description enriches their meaning substantially. It explains accepted input forms for 'company' (ticker, CIK, ISIN, name), the special ISIN-to-LEI resolution path, and the drug parameter's return of RxCUI, ingredient, and brand. This goes well beyond the schema's baseline 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 uses a specific verb ('resolve') and clearly states the resource (user-spoken NAME to canonical/official identifiers). It provides concrete example queries and distinguishes its scope by stating 'Use FIRST whenever you have a name but need an ID', which separates it from sibling tools like entity_profile or compare_entities.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains it replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of the highest bar for exclusionary guidance.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable details about internal probing with ai_visibility_check, ranking, and return format (score, confidence, signal density). No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence provides essential 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?

Despite lack of output schema, the description specifies the return format (ranked list with score, confidence, signal density) and references internal dependency on ai_visibility_check, providing sufficient context 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%, so baseline is 3. The description adds semantic value by explaining that the first entity is treated as the subject and the rest as competitors, guiding usage 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 compares AI visibility across multiple entities, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) by emphasizing the side-by-side comparison.

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

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

The description provides a clear use case (competitive AI-marketing audits) with an example question. It implies alternatives but does not explicitly state when not to use or directly name alternatives, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed field, and NPM-only restriction. 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 detailed but well-organized, with key information upfront (composite check, sources) followed by specifics. Could be slightly more concise, but 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?

With no output schema, the description clearly lists the return fields (summary block, advisories, links, alternatives) and explains failure modes. Covers all necessary aspects for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions. Description adds useful context: scoped packages accepted, version defaults to latest, and explains the composite nature. Adds value beyond schema.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, combining multiple data sources. It specifies the purpose as answering questions about safety, popularity, and size, and distinguishes from siblings by limiting to npm ecosystem in v1.

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

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

Explicitly tells when to use (agent asks about adding an npm package) and when not to use (other ecosystems should use deps.dev:version directly). Also mentions partial failures and timeout behavior.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable context: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character limit (200K), truncation behavior, and output features (offsets). 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 covering purpose, usage, and technical details. Every sentence serves a clear function, front-loaded with key info. No redundancy.

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

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

Given no output schema, the description adequately explains return format (passages with offsets and scores), limits, embedding details, and pairing advice. Complete for tool selection and invocation.

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

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

Schema coverage is 100% (all parameters described). The description adds natural-language examples for 'query' and clarifies 'text' as fetched document, exceeding baseline. 'limit' default is noted implicitly.

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 semantic search inside a fetched record, using specific verb 'search' and resource 'record'. It distinguishes from siblings like 'ask_pipeworx_grounded' by explaining the complementary workflow.

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 use when the record is too large for the prompt and highlights pairing with 'ask_pipeworx_grounded'. However, it does not explicitly state when not to use it.

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

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

The description goes beyond annotations by detailing delivery channel behaviors (always-on feed, SMS caps, webhook auto-disable), auth requirements, and type-specific parameters. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose and organized sections for requirements, types, and delivery. It is detailed but could be slightly more concise without losing essential information.

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

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

Given the tool's complexity (multiple types, nested params, delivery options), the description covers all critical aspects: OAuth requirement, type-specific params, delivery details, and behavioral notes (auto-disable, signing secret). No output schema exists, but the return value is stated.

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

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

With 100% schema coverage, the description adds significant value by providing examples and clarifying semantics (e.g., item codes for sec_8k, topic for polymarket_edge), exceeding the schema's minimal descriptions.

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

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

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

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

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

The description provides clear context for usage, including requirements (Pipeworx OAuth account) and supported types, but does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns dynamic content from live catalog, can be called with or without topic. 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 structured with example queries, purpose, category list, usage instructions. Front-loaded purpose. Slightly verbose with repeated phrasing but still efficient.

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

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

No output schema, but description explains return format: category-bucketed example questions with tool+argument shapes. Covers topic parameter effect. Complete for this simple tool.

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

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

Schema coverage is 100% with description for topic. Description adds meaning by explaining effect of omitting vs. specifying topic and listing example values. Adds value beyond schema but schema already does heavy lifting.

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

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

The description clearly states that this tool returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings by being the initial discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' Provides clear when-to-use and alternatives.

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

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

Annotations indicate mutation and non-destructive idempotent behavior. The description adds ownership enforcement and deactivation semantics (not deletion), providing behavioral context beyond annotations.

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

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

Two sentences, no wasted words. Information is front-loaded with the key action and then behavioral details.

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

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

The description covers the effect and side effects (deactivation, ownership, historical events) for a simple one-param tool. No output schema exists, but return value is not critical for this action.

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

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

Schema description coverage is 100%, and the parameter 'id' is clearly described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond this.

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 'Cancel a subscription by id', which is a clear verb+resource pairing. It distinguishes itself from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists).

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 mentions ownership enforcement and that the row is deactivated (not deleted), implicitly guiding usage. It references 'recent_alerts' for historical events, but does not explicitly state when to use alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description gives crucial behavioral context: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covers it), the routing to live vs structured sources, and the exact percent-delta math. This materially helps the agent interpret results correctly.

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 with useful information: examples, routing, verdict list, error semantics, and efficiency note. It is a bit long, but every sentence serves a purpose. The 'IMPORTANT for callers' callout is well-structured for the key caveat. Slightly verbose but appropriate 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?

Even without an output schema, the description covers the return value (verdict, actual value, citation), enumerates all verdict types, explains the critical error semantics, and clarifies the two fallback paths. It leaves no major ambiguity about what the agent should expect when invoking this tool.

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

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

Schema coverage is 100% with descriptions for both claim and tolerance_pct. The description adds value by providing example claims and explaining that tolerance_pct can be set to 1-2 for hallucination detection, which is not in the schema. It doesn't fully compensate for the range details, but adds enough to go above baseline.

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 identifies the tool as natural-language claim verification ('fact check', 'verify the claim'), with explicit usage examples and a distinct output (verdict + evidence). It differentiates from sibling tools by mentioning the SEC EDGAR + XBRL fast path and the grounded pipeline, and by stating it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional routing guidance (financial vs other claims). However, it does not explicitly name alternative sibling tools (e.g., ask_pipeworx_grounded) or state when NOT to use it, which prevents a 5.

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