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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context: it routes to 5,334 tools across 1,393 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. It also mentions handling breaking news via live news feeds. This goes beyond annotations without contradicting them.

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

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

The description is long but dense and well-structured. It starts with a strong imperative ('PREFER OVER WEB SEARCH') and immediately establishes scope, then provides examples, escalation paths, and alternative tools. Every sentence adds value, though the length could be slightly trimmed without losing clarity. It earns its place given the tool's broad applicability.

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 having no output schema, the description fully explains the tool's behavior: structured answers with citations, routing to a large tool ecosystem, and the ability to handle a wide range of factual queries. It also covers expected response format (structured answer with pipeworx:// URIs), speed ('one fast call'), and integration with news feeds. This is a complete description for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage, with all six parameters documented as aliases for 'question' and a description for each. The description does not add new parameter-level semantics beyond providing example queries, which are illustrative but not essential. Since the schema already carries the parameter documentation, the baseline of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions about current or historical data across a broad range of domains (SEC filings, FDA drugs, FRED/BLS, patents, real estate, etc.) using authoritative structured data. It explicitly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs, so an agent can immediately understand its specific purpose relative to other 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 gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases like 'what is', 'look up', 'find', and provides concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). It also states when to step up to ask_pipeworx_grounded or deep_research, and notes that ask_pipeworx handles breaking news through news feeds, making the decision tree very clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable context about the live experimental state (candidate routing improvements may be active), the fact that it is currently identical to ask_pipeworx, and that it 'Falls back to nothing' — a full working router, not a stub. This goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the key identity ('Beta version of ask_pipeworx'), and each sentence contributes meaningful information: status, usage guidance, and reassurance that it's a full router. It is not overly verbose for the complexity of explaining a beta variation.

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 single-parameter router, the description is quite complete: it explains the beta status, current exact-match state, usage instruction, and safety profile via annotations. There is no output schema, but the description mentions 'same response shape' as ask_pipeworx, which suffices if the agent knows that sibling tool. Given the absence of nested objects and minimal params, the contextual coverage is strong.

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 six parameters are clearly documented as aliases for 'question', each with its own description. The description doesn't add parameter-specific semantics beyond referencing 'same arguments' as ask_pipeworx, but the schema carries the full burden. Baseline 3 applies because the schema is sufficient and the description provides marginal extra value.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,334 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental nature and live candidate routing improvements. The verb is implicit but the resource and scope are specific.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that results are compared against the stable router, implying when this experimental edge is desired. While it doesn't explicitly list when not to use it, the contrast with the stable router offers clear context. Alternatives are not fully enumerated, but the stable ask_pipeworx is directly referenced.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses return format with evidence and confidence, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the extra LLM call cost. It provides detailed behavioral context without contradicting 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 the core purpose, followed by routing details, return/refusal shapes, and usage context. Every sentence earns its place, though it is somewhat dense with refusal reason lists and edge cases; still appropriately sized 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?

With no output schema, the description fully specifies the success return (answer, evidence, confidence, source, fetched_at) and failure return (answer:null with specific refusal_reason values). It covers high-stakes usage scenarios, refusal behavior, and cost tradeoff, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with all six parameters being aliases for the same 'question' field. The description does not add parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema fully handles parameter documentation.

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

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

The description states a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and details how it extracts answers using only tool results. It clearly distinguishes from sibling tools like ask_pipeworx by emphasizing grounded evidence and refusal behavior.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' It also notes the tradeoff of an extra LLM call, giving clear when-to-use vs. alternatives.

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

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

The description 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?

Beyond annotations (read-only, open-world, idempotent), the description discloses auth requirements (GitHub sign-in, paid for thorough), latency ranges, output shape (findings packet with gaps[], contradictions[], hop fields, citation_uri), and semantic excerpting behavior. 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: it front-loads auth and the core function, then covers use cases, depth behavior, output details, and latency. Some redundancy (e.g., 'NOT open-web search' stated twice) but each section adds necessary context for a complex 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?

With no output schema, the description fully compensates by detailing the findings packet fields, explicit gaps[], contradictions[], hop flag, citation_uri, and semantic excerpting. It also covers auth, latency, and alternative tools, making the description complete for agent decision-making.

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

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

The schema already covers depth with detailed semantics, but the description adds the paid-plan requirement for 'thorough' and provides example questions for the 'question' parameter. It also clarifies what depth values return (e.g., contradictions for standard/thorough), slightly extending schema info.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources' and explains it decomposes questions into facets routed across 5,334 tools. It also differentiates from siblings by contrasting with ask_pipeworx for single lookups and breaking news.

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

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

Explicitly says 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' plus 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. Also warns about account requirements and directs signed-out users to an alternative.

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

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

Annotations declare readOnlyHint 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 provide no safety hints; description adds rate limit (5 per identifier per day), cost (free), quota impact (doesn't count), and processing cadence (daily digests). Full disclosure beyond annotations.

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

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

Single paragraph, front-loaded with purpose, then usage, then details. Every sentence serves a purpose—no filler, no repetition.

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

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

For a feedback tool, description covers all: what to submit, what not to submit, rate limits, cost, processing. No output schema needed as feedback is not expected to return data. Complete for its 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% but description adds significant value: explains each type enum in narrative, instructs on message specificity, and clarifies context is optional and its usage. Adds context beyond raw schema.

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

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

Description states specific verb ('Send feedback') and resource ('Pipeworx team'), enumerates feedback types (bug, feature, data_gap, praise). Distinguishes from sibling tools (e.g., ask/discover/research) by being the sole feedback mechanism.

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 (wrong/stale data, missing tool, praise), what not to do (don't paste user prompt), and includes behavioral constraints (rate-limited 5/day, free, no quota count). Though no alternatives named, the tool's unique purpose makes guidance 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 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?

Describes internal cascading through lookup endpoints, return details per type (ticker, CIK, RxCUI, citations), and auto-disambiguation. Adds context beyond annotations (readOnlyHint, idempotentHint).

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

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

Well-structured with examples first, then guidance, then type details. Slightly verbose but every sentence adds value; no redundancies.

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

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

Fully explains purpose, supported types, input variations, and output format. No output schema needed; annotations cover safety. Complete for a lookup tool.

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

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

Schema coverage 100%; description adds meaning by specifying acceptable input formats for each type (e.g., ticker, CIK, name for company) and auto-disambiguation behavior.

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

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

Clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples (ticker, CIK, RxCUI). Distinguishes from sibling tools like search_within or entity_profile by focusing on identifier lookup.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Lists supported types and input formats, and implies replacement of manual lookups, guiding effective use.

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

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

Annotations already 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral details: the dual pipeline (SEC EDGAR vs. grounded), the use of exact percent-delta math, and the return format (verdict, actual value with citation, reasoning). No contradiction with annotations.

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

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

The description is lengthy but well-structured, front-loading usage examples and key phrases. Every sentence carries weight, though it could be marginally more concise without losing clarity. Overall, it effectively communicates without padding.

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 having only 2 parameters and no output schema, the description fully explains the return structure (verdict, value, citation, reasoning) and covers edge cases like approximate correctness and tolerance. Annotations are present, and the description compensates for the lack of output schema by detailing the output.

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

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

Schema coverage is 100% with both parameters described. The description adds value by explaining that tolerance_pct overrides the implied tolerance with a default cap of 5%, and provides examples for the claim parameter. This supplements the schema without redundancy.

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 multiple specific verb phrases ('fact check', 'verify', 'confirm or refute') and clearly identifies the resource ('natural-language claim verification against authoritative sources'). It distinguishes itself from sibling tools by explaining that it replaces 4-6 sequential calls, making its purpose unmistakable.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct'). It also differentiates between company-financial and other claims, providing clear routing logic. It does not explicitly state when not to use it, but the context is sufficient.

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