Macro Snapshot

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by disclosing cost implications (free default vs. BYO key for Anthropic) and the return format per model. 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 a single, well-structured paragraph that front-loads the main action, default behavior, key condition (API key), return format, and use cases. Every sentence adds 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?

Given no output schema, the description explains the return structure (per-model fields + combined view). It covers parameter usage and main use cases. There is no need for pagination or error handling details for this probing tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context beyond schema: default model, API key format, and the role of the 'context' parameter for disambiguation. This meaningful addition justifies a score of 4.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It uses specific verbs ('probe', 'score') and identifies the resource ('LLMs'), distinguishing it from sibling tools like 'scan_competitor_ai_presence' or 'deep_research'.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and states when to provide an API key. However, it does not explicitly contrast with sibling tools or specify when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond that: it mentions routing across thousands of tools, stable citation URIs, 'one fast call', and that it works on every tier. 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 longer than average but well-structured and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH', 'START HERE'). It contains examples and sibling differentiation, each sentence earning its place, though it could be trimmed slightly without loss.

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

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

For a complex, routing-capable tool with no output schema, the description covers purpose, usage triggers, output format (structured answer with citations), and alternatives. It lacks explicit limitations (e.g., what kinds of questions it cannot handle), but given the breadth and the annotations, it 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% (all parameters described, including aliases). The description adds minimal extra meaning about parameters; it just shows example questions, which is helpful but not a significant extension over the schema's clear 'question' field 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 it routes questions to 5,529 tools across 1,455 sources and returns structured answers with citations. It uses specific verbs like 'routes' and 'returns', and explicitly distinguishes itself from siblings by naming alternatives when to step up, 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?

It provides explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for multi-part questions). It even lists trigger phrases and examples, making usage criteria exceptionally 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 read-only and idempotent, but the description adds crucial behavioral context: it is a live experimental router, may have candidate routing changes enabled, and currently matches ask_pipeworx exactly since no candidate is active. It also clarifies that it is a full working router with no fallback, which is valuable beyond annotations.

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

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

The description is slightly long but every sentence carries essential information: beta status, identity with ask_pipeworx, current state of no active candidate, and usage instruction. It is front-loaded with the core purpose and well-structured.

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

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

Given the tool's complexity as a universal router, the description sufficiently explains its scope (5,529 tools), behavior (experimental edge), and response shape (same as ask_pipeworx). It doesn't provide an output schema, but points to ask_pipeworx for details, which is adequate for an agent to operate 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 alias parameters clearly described. The description adds minimal parameter information beyond saying 'same arguments' as ask_pipeworx, which is helpful but not necessary since the schema already documents each alias.

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 is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape, but with candidate routing improvements. It distinguishes from siblings by explicitly referencing ask_pipeworx and noting the experimental edge.

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

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

It provides direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It implies the alternative of using the stable ask_pipeworx for non-experimental needs, though it doesn't explicitly state 'when not to use' this version.

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

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

Discloses detailed behavioral traits beyond annotations: extra LLM cost, strict use of tool result content only, and specific refusal reasons. No contradiction with annotations; complements readOnly/idempotent hints with operational specifics.

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?

Despite length, the description is efficiently structured with front-loaded purpose, behavioral details, and usage guidance. Every sentence contributes value, using punctuation to organize the dense information.

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

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

For a tool with no output schema, the description fully covers the return shape, refusal reasons, and success behavior. It also explains the underlying routing mechanism and cost, making it comprehensive for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with well-documented aliases for the question parameter. The description does not add parameter-level detail, but none is needed given the schema's clarity. Baseline 3 applies.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' for high-stakes reads, distinguishing it from ask_pipeworx by emphasizing extraction grounded strictly in tool results. It names specific use cases and differentiates from the sibling by the refusal/evidence 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?

Explicitly states when to use (when answers will be quoted, cited, or acted on and inventions are unacceptable) and when to prefer the alternative (casual lookups, citing extra LLM cost). Names the alternative tool and provides clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral context: it explains that low-confidence matches short-circuit and block analysis, closed markets return a specific status, fan-out logic, resolution-rule risk, and warning about medium/low matches. This goes far beyond annotations.

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

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

The description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded purpose. Every sentence adds value, covering many details. However, it could be slightly more concise; some details might be better in an output schema or separate docs.

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

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

Given no output schema, the description thoroughly explains all response shapes, including edge cases like low-confidence match, closed markets, wide spreads, cancellation rules, and news fallback. It is comprehensive enough for an AI agent to understand the full behavior and response structure.

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

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

Schema description coverage is 100% (all 3 parameters described). The description repeats the parameter formats (slug, URL, text for 'market') but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate as the description is adequate but not additive.

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

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

The description clearly states the tool researches a single Polymarket bet by pulling relevant Pipeworx data. It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on a specific bet, not aggregates. The verb 'Research' and resource 'a Polymarket bet' 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?

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear when-to-use guidance. It also implies that this tool is for individual bet analysis, not for scanning multiple bets (which siblings do). No exclusions are needed given the context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA/clinicaltrials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with example queries and key guidance. Every sentence adds useful information, though the last sentence about replacing 8–15 lookups is somewhat redundant. It could be slightly condensed but remains efficient for the complexity.

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

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

Given the tool has 2 parameters with full schema coverage, no output schema, and annotations covering safety, the description adequately explains return values ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. It also notes the tool's efficiency improvement, making it complete for agent understanding.

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

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

Schema coverage is 100% with descriptions. The description adds concrete examples (e.g., '["AAPL","MSFT"]' for companies, '["ozempic","mounjaro"]' for drugs) and clarifies the meaning of the 'type' parameter beyond the enum. This adds value 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 explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides example queries like 'X vs Y' and 'rank these companies', making the purpose crystal clear. It also distinguishes from sequential single-lookups.

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

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

The description says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies the efficiency gain ('Replaces 8–15 sequential lookups'). This gives clear when-to-use guidance and identifies alternatives (entity_profile).

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond them: account/paywall requirements, the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), explicit gaps[] never invented, contradiction detection, hop fields, semantic excerpting, and latency expectations. This gives the agent a strong behavioral model with no contradiction.

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

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

The description is long but every sentence carries high-value detail about usage, output, and caveats. It front-loads the most critical operational constraint (account required) and alternatives. A slight deduction for repetition of the contradictions[] behavior and for density that could be tightened, but there is no filler.

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

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

There is no output schema, so the description must carry the burden of explaining return values, and it does: findings packet structure, gaps[], contradictions[], hop field, citation_uri, and excerpting behavior. It also covers timing, account tiers, and failure modes (empty gaps for non-structured topics), making it complete for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches the parameters beyond the schema: it explains that 'question' can be broad/multi-part and that 'depth' controls facet count and recovery behavior (gap-recovery hop, contradiction scan). This adds useful semantic detail over the structured 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call', and explicitly differentiates from siblings like ask_pipeworx ('this is NOT open-web search'). It also explains the decomposition and routing behavior, leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and direct alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and when deep_research returns mostly empty gaps[], providing exclusions as well as recommendations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that returns top-N tools with full schemas and examples, ready to call. No contradiction, and context is useful beyond annotations.

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

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

Description is 4-5 sentences, front-loaded with purpose, then context, output details, and usage guideline. Every sentence adds 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?

Despite no output schema, the description fully explains what the output contains. All six parameters are covered. The description is complete for an agent to understand 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?

All 6 parameters are fully described in the input schema (100% coverage). Description reinforces that query accepts natural language, but does not add new semantic 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 it finds tools by describing data or task, explicitly listing many domains. It distinguishes itself from sibling tools like ask_pipeworx or deep_research by being a discovery tool, not for direct answers.

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

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

The description explicitly says 'Call this FIRST when you have many tools available' and 'Use when you need to browse...'. It implies not to use when you already know the tool, but does not explicitly list 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 adds significant behavioral detail beyond the annotations: it fans out across multiple sources, returns specific fields, notes the patent soft-fail timeframe, and explains the news fallback chain. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description is consistent with 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 front-loaded with example queries and packs a lot of information into one dense paragraph. While not using bullet points, it remains fairly concise. Minor improvement could be splitting into clearer sections.

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 input requirements, return fields, source behavior, fallback logic, and limitations (patent soft-fail, name unsupported). Without an output schema, it adequately describes the return values. However, it could mention potential variability in returned fields 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%, but the description adds value by clarifying input formats (e.g., ticker or zero-padded CIK) and reinforcing that names are not supported. It also explains the 'type' parameter is restricted to 'company' with future plans. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides example queries and explicitly distinguishes from sibling tools by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and directing to resolve_entity for names.

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: 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view'. It also states when not to use: if the user only has a name, use resolve_entity first. This provides clear context and alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds value by explaining the action as 'delete' and 'clear sensitive data', confirming the destructive nature 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?

Three sentences, all essential and front-loaded with the action. No redundancy or filler.

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

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

For a one-parameter tool with annotations and a clear schema, the description sufficiently covers purpose, usage, and pairing. No gaps remain.

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

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

Schema coverage is 100%, and the parameter description 'Memory key to delete' is already clear. The description does not add extra semantic meaning beyond referencing 'by key', so it meets 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 verb 'Delete' and the resource 'previously stored memory by key'. It is distinct from the sibling tools 'remember' and 'recall' implicitly by specifying deletion vs. storage vs. retrieval.

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 specific scenarios for use: stale context, task completion, clearing sensitive data. It does not explicitly state when not to use or name alternatives, but the context is clear and helpful.

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 explains the process (fetches page, extracts title/description/links, emits markdown) beyond what annotations provide. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description, and no contradictions exist.

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-loading the main purpose and listing use cases efficiently. Every sentence adds value without redundancy or wasted words.

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

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

Given the tool's simplicity (2 params, no output schema, rich annotations), the description covers purpose, use cases, and output format ('single text blob'). It is complete enough for an agent to understand 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?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema for parameters 'url' and 'max_links'; it merely mentions 'for any URL' which aligns with the first parameter.

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

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

The description clearly states the tool generates a production-ready llms.txt file for AI crawlers, specifying the action (generate), resource (llms.txt), and context (any URL). It distinguishes from siblings by focusing on this specific output format, which is unique among the listed 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 provides clear use cases: getting a client's site indexed, drafting for own projects, or auditing competitors. It implies when to use the tool but does not explicitly state alternatives or when not to use it, which would improve guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that results are 'observations most-recent-first plus the latest value', and mentions default/max limit. 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?

Two concise sentences, front-loaded with purpose and usage, no fluff. 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 simplicity of the tool (read-only, two parameters) and rich annotations, the description is sufficient. It covers the return format and common use cases, though it could mention that the output is an array of observations.

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 baseline is 3. The description enriches parameters by listing common series IDs and stating default and maximum limit values, adding 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 specifies the verb 'Read' and the resource 'FRED series', with examples of common IDs. It distinguishes from sibling tools like 'macro_snapshot' by explicitly stating it can drill into any FRED series.

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 implicitly guides when to use this tool (to get recent history for any specific FRED series) and contrasts with 'macro_snapshot'. It provides many common IDs as usage context, but no explicit when-not or alternative naming.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description's job is lighter. It adds value by noting default active-only behavior and the effect of include_inactive parameter. Describes returned fields, enhancing transparency 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?

Two sentences: first states purpose and output fields, second gives usage guidance. No fluff, every sentence is justified and front-loaded. Excellent conciseness.

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

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

Given low complexity (1 optional param, no output schema), the description covers purpose, usage, and behavior adequately. It lists return fields and default behavior. No missing critical information; could mention pagination or limits but not needed 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 covers the only parameter (include_inactive) with 100% description coverage, so description doesn't need to add much. It mentions the parameter implicitly but adds no new semantics 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?

Description clearly states 'List the caller's active subscriptions', providing specific verb and resource. It also enumerates return fields (id, type, params, etc.), making the output clear. Differentiates from siblings like subscribe/unsubscribe by focusing on listing.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Tells when to use and provides practical context, distinguishing it from other actions.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). Description adds behavioral details: it composes 16 FRED series with live crypto, runs them in parallel, returns structured dashboard and callouts. 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 not overly lengthy. It front-loads the main purpose and lists key outputs. Slight redundancy in listing all series could be trimmed, but overall good.

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 parameters and no output schema, the description fully explains what the tool does and what it returns (dashboard with callouts). It is complete and self-contained.

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?

No parameters exist, so baseline is 4. The description handles this perfectly by specifying 'No arguments' and not needing to explain any inputs.

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: providing a comprehensive snapshot of the US/global economy with a specific list of indicators. It distinguishes from siblings by noting it consolidates multiple indicators into one call.

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

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

Explicitly advises using this tool instead of fetching ten indicators separately, implying when to use (broad snapshot) and when not (if only one indicator needed). Could be more specific about alternatives.

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

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

Annotations are all false, but the description adds rich behavioral context: it states the operation returns a claim_token, can be used later to check resolution, is rate-limited to 5 per day, is free, and doesn't count against tool-call quota. It also tells the agent not to paste end-user prompts. This goes far beyond the minimal annotation info.

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

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

The description is longer than average, but every sentence earns its place: purpose, use cases, exclusions, message constraints, token workflow, rate limits, and quota impact. It is front-loaded with the core action and proceeds logically. Slightly dense but not wasteful.

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

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

Despite having no output schema, the description explains what the tool returns (a claim_token) and how to use it later. It covers content guidelines (don't paste end-user prompt), scope boundaries (only Pipeworx tools), and operational limits (rate limit, quota). For a feedback tool with nested context objects, this is fully 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 description coverage is 100%, so baseline is 3. The description adds some context (e.g., the claim_token usage pattern, the workflow of filing and returning), but it doesn't add new meaning to the individual parameter definitions beyond what the schema already states. It's adequate but not a major enhancement.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling research/query tools by framing it as feedback about Pipeworx tools themselves, not a request for information.

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a concrete exclusion—tools from other MCP servers—and tells the agent to file those elsewhere. The claim_token workflow is explained clearly.

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 caching behavior (5min-1h) and data source (CF analytics-engine, no PII), which provides useful 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 concise paragraphs with front-loaded main output. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one optional param and no output schema, the description covers purpose, usage, caching, data source, and use cases completely.

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

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

Schema has one param with enum and description. The description adds semantic nuance: shorter windows for hot trends, longer windows for steady-state demand, enhancing understanding beyond the enum.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It distinguishes from siblings like discover_tools by focusing on real-time popularity data.

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?

Three explicit use cases are given, covering discovery, validation, and alignment. It does not explicitly state when not to use, 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.

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: semantic anchor for cross-event pairs (Jaccard similarity ≥0.30), partition filter for placeholder slugs, fill check against live CLOB depth. No contradictions with annotations.

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

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

Although lengthy, every sentence adds value. The description is structured logically: main purpose, then detailed breakdown of each mode with examples, then behavioral details like semantic anchor and fill check. Front-loaded with core function. No wasted words.

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

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

Given the tool's complexity (two optional parameters, no output schema), the description covers all needed aspects: input modes, internal processing (monotonicity, partition checks, fill check), output structure (opportunities[], partition_check), and edge cases (placeholder filtering, fill check thresholds). It is sufficiently complete for effective use.

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

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

Schema coverage is 100% (both event and topic described). The description adds significant meaning beyond the schema: event can accept full URLs, topic triggers a cross-event scan with internal search logic. It provides examples of valid slugs and topic questions, greatly aiding 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?

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific examples, making it easy to understand what the tool does relative to siblings.

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

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

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. The description also explains when not to trade based on fill check results, offering clear usage boundaries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details such as caching at 1h, response structure with diagnostics, and tradeable-edge knobs, which go beyond the annotations. No contradictions.

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

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

The description is verbose but front-loaded with the core purpose. Each sentence adds specific, non-redundant detail such as model families, knobs, and response elements. While dense, it avoids fluff and justifies its length given the tool's complexity.

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

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

With 9 parameters, no output schema, and high complexity, the description comprehensively covers the response structure (by_segment, diagnostics), caching behavior, filtering knobs, and even edge cases (Fed bets, placeholder filters). Ideal for an AI agent to understand 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds significant context for many parameters, including slippage explanation, tradeable-edge knobs, and partition filtering logic, which enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, explicitly stating its purpose is 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by providing specific model families and response segments.

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

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

The description positions the tool as a discovery engine for bettors and provides filtering knobs (min_kelly, min_edge_pp, etc.) to guide when to use it. However, it does not explicitly state when not to use this tool or directly compare to alternatives like polymarket_arbitrage, so it loses one point.

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 and idempotentHint. Description adds valuable context: that decay is computed from daily closes (not intraday), that snapshots have a 60-day TTL, and that gaps in snapshot_dates indicate no scan occurred. This goes beyond annotations.

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

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

The description is dense and informative but could be more structured. It front-loads key purpose but then includes response format and limits in a single paragraph, which may be harder to parse.

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

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

Despite no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) with field meanings. It also covers limits and assumptions, making it complete for a read-only data tool.

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

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

Schema description coverage is 100%, and the description restates the parameters with default and max values, which adds minimal value. Baseline 3 is appropriate since the schema already covers semantics.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. This distinguishes it from siblings like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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

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

Explicitly explains when to use: to distinguish between a fresh wide edge and an old one, with the example that a 3-week-old wide edge exists for a reason. Also details output structure and limits, though does not explicitly say when not to use.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds behavioral context: it performs a check but warns about risks like partial basket fills converting arb into unhedged directional positions. No contradictions.

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

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

Long but dense description with bold headers for REQUIRES, SINGLE-MARKET, BASKET. Every sentence is informative. Could be slightly more concise, but structure aids readability.

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

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

No output schema, but description lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and covers both modes with defaults and risk warnings. Comprehensive for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds semantic meaning: explains single-market vs basket mode, default values, and how size_usd is interpreted (max spend on buys, target proceeds on sells for single-market; settlement notional for basket). Adds significant context.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return fields and 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 why: theoretical overround on thin books is not capturable, and partial basket fills lead to unhedged directional positions.

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

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

Adds extensive behavioral detail beyond annotations, including compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype counters. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is dense and well-structured, front-loading purpose and modes, then detailing response and safety fields. Every sentence contributes, though slightly verbose for the complexity.

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

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

Covers all aspects: modes, response structure, field meanings (compatibility_warning, temporal_alignment, skipped counters), and usage caveats. No output schema, but response is adequately described.

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

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

Schema coverage is 100%, but the description adds meaningful context: lists all 10 topic shortcuts, explains override behavior, and provides examples. Adds value 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using specific verbs like 'cross-venue spread' and 'auto-fetch'. It distinguishes itself from sibling tools as no other tool in the list serves this purpose.

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

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

Provides explicit guidance on two modes (topic vs explicit tickers) and warns about the rarity of real spreads and the meaning of compatibility warnings. Lacks explicit 'use this tool when' phrasing, but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail ('Scoped to your identifier'), pairing behavior, and the dual behavior of omitting vs providing key. Does not mention error handling or rate limits, but annotations cover safety profile.

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 pack core action, usage context, scoping, and tool pairings. Front-loaded with purpose, no redundant phrases. 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 optional param and no output schema, the description covers purpose, usage, scoping, and relationships. Could mention what happens when key is missing (returns null/error?), but not essential.

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

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

Schema coverage is 100% with good parameter descriptions (including 'omit to list all keys'). The description repeats this and gives a concrete example key ('user_research_topic'), which adds marginal value. Baseline 3 is appropriate since schema already does the work.

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

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

The description clearly states the verb 'Retrieve' and 'list' with the resource 'saved keys/values'. It explicitly distinguishes from siblings 'remember' and 'forget' by mentioning pairing. Concrete examples (target ticker, address, research notes) clarify usage.

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?

Describes when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget. Does not explicitly list when NOT to use or provide alternative tool names, but the context is clear.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description reveals that mark_read flags events as read, affecting subsequent calls. It also describes the content of returned events, providing full behavioral context.

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

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

The description is concise and front-loaded with the main purpose. Each sentence adds necessary information without redundancy, making it efficient and easy to parse.

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

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

Despite no output schema, the description fully explains the return format and fields. All 5 parameters are covered with behavioral context, and the tool's role among many siblings is clear.

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

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

While schema descriptions cover all 5 parameters, the description adds value by providing an example for type ('sec_8k') and explaining the effect of mark_read. This enhances understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying what is returned (source, citation_uri, raw payload). It distinctly identifies the tool's function among many siblings.

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

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

Explicitly mentions that polling works fine and provides an alternative endpoint for scripts/dashboards. Also advises on filtering by type and since, and explains mark_read behavior for controlling what appears next.

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

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

Adds valuable context beyond annotations: fans out to multiple sources, fallback, soft-fail, return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

Front-loaded with examples and purpose. Includes many details, but could be slightly more concise. Still efficient for the complexity.

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

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

Complete for a tool with multiple sources, fallback, and varied inputs. Explains return structure and use cases despite no output schema.

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

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

Schema descriptions cover all parameters; description adds examples for 'since' (ISO date, relative shorthand) and 'value' (ticker or CIK). Adds marginal value over 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 it provides a change feed for a company, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. Examples like 'What's new with X' and comparison with entity_profile distinguish it from siblings.

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

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

Explicitly says when to use (e.g., 'latest on Y', 'news on Tesla') and when not to (use entity_profile for static profile). Includes fallback logic for GDELT→GNews and soft-fail for USPTO.

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

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

Description adds behavioral details beyond annotations: key-value pair scoped by identifier, persistence for 24 hours for anonymous sessions. Annotations already indicate idempotent and non-destructive, but description adds important expiration and scoping context.

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

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

Three concise sentences: first states purpose, second gives usage guidance, third adds behavioral details. Front-loaded and 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?

For a simple tool with no output schema, description covers input and use cases well. Does not explicitly state return value, but typical save operation return (e.g., success) is implied. Slight gap for output description.

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 key and value. Description provides example keys but does not add significant meaning 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?

Description clearly states 'Save data the agent will need to reuse later', identifying a specific verb and resource. It distinguishes from siblings like recall and forget, and explains the scope across conversations or sessions.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides context on persistent vs. anonymous sessions and pairs with recall and forget, offering clear usage guidance.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful context beyond these: identifiers are labeled with their source, unresolved identifiers are explicitly reported under 'unresolved' rather than omitted, and LEI/FIGI enrichment degrades gracefully if external services are unavailable. These behavioral details are not visible in 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 longer than necessary, particularly the opening list of example queries which could be condensed. However, it is well-structured after that point, with each sentence providing substantive details about capabilities, supported types, and fallback behavior. It earns its place despite minor 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?

With no output schema, the description must explain return values and behavior, and it does so thoroughly. It details company output (CIK, ticker, LEI, FIGI, source labels, unresolved list) and drug output (RxCUI, ingredient, brand, citation), plus graceful degradation. This is a complete context for a 2-parameter tool.

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

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

Schema description coverage is 100%: both 'type' (with enum) and 'value' (with examples) are already fully described. The tool description restates this information without adding new parameter-level meaning. Therefore, baseline of 3 is appropriate; the schema already carries the semantic weight.

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 a specific purpose: resolve user-spoken names to canonical/official identifiers. It explicitly mentions the resource (identifiers) and the action (resolve), and differentiates from siblings with 'Use FIRST whenever you have a name but need an ID.' It also breaks down supported entity types (company, drug), making the scope 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 provides explicit usage direction with 'Use FIRST whenever you have a name but need an ID,' and explains that it replaces 2-3 manual lookups. It also clarifies which input formats are acceptable per type, giving clear context for when to choose this tool over 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, signal density per entity, and treats the first entity as the subject for narrative. This adds value 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 concise sentences, front-loaded with the main action ('Compare AI visibility...'). Every sentence adds value without redundancy. The description is efficiently structured for quick comprehension.

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 (multi-entity comparison, aggregation from another tool), the description explains the process, the ranking, and the output fields (score, confidence, signal density). It also notes the narrative bias. No output schema exists, so the description adequately covers what the agent will receive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: 'entities' must be 2-8 with first as subject; 'models' defaults to workers-ai and requires _apiKey for anthropic; '_apiKey' passed to api.anthropic.com; 'context' disambiguates common names with example. This enriches the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, ranking them by score. It uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and specifies the resource (AI visibility). It distinguishes itself from sibling ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

The description provides a use case ('competitive AI-marketing audits') and gives an example question. However, it does not explicitly state when not to use this tool or list alternatives (e.g., ai_visibility_check for a single entity). The context is clear but lacks exclusionary guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds key behavioral traits: fans out across two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts.

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 front-loaded with the composite nature. Though slightly long, every sentence provides necessary information without redundancy.

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

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

Given no output schema, the description lists all return fields (summary block, per-advisory detail, links, alternative versions) and explains partial failure behavior. It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages are accepted and that version defaults to latest, providing additional 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?

The description clearly states it's a composite check for npm packages covering license, advisories, version history, bundle size, and tree-shaking support. It is distinct from sibling tools, none of which focus on package 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?

Explicitly states when to use: when an agent asks about package safety, popularity, or cost. Also clarifies it's NPM-only in v1 and mentions fallback to deps.dev for other ecosystems.

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

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

Discloses truncation at 200K chars, embedding model (BGE-base-en), window size, similarity metric, and offset for quote verification. No contradiction with annotations (readOnly, openWorld, idempotent).

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 yet comprehensive: front-loaded key info, each 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?

Explains return values (passages with offsets and scores) despite no output schema. Fully covers tool behavior and limitations.

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 example queries, default limit, and text truncation flag, providing additional 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?

Description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). Distinguishes from sibling ask_pipeworx_grounded by describing how they pair.

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

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

Explicitly states when to use: when record is too large for prompt. Mentions sibling tool and provides guidance on pairing with ask_pipeworx_grounded for grounding.

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 provides extensive behavioral details beyond annotations: requires OAuth, returns subscription ID, delivery channels limits (10/day SMS), webhook auto-disable after 10 failures. No contradiction with annotations.

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

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

The description is fairly long but well-structured, front-loading the purpose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given complexity (3 params, nested objects, no output schema), the description is highly complete: explains types, parameters, delivery, requirements, limits, and response content (subscription ID).

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 substantial meaning: explains each type and params structure, delivery options with examples and constraints, and webhook signing secret.

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains when to use the tool (to subscribe), prerequisites (Pipeworx OAuth account), and limitations (anonymous/BYO cannot persist). It does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context (category-bucketed examples, tool+argument shape, live catalog) without contradiction, and provides usage behavior (optional topic narrowing).

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 structured logically, but is somewhat lengthy. Every sentence adds value, though it 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 the tool's role as an onboarding guide with no output schema, the description fully explains what it returns, how to call it, topic options, and when to use it relative to other tools. No gaps.

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

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

Schema coverage is 100% with topic description listing options. The description repeats these options in natural language and adds the nuance that omitting topic yields cross-category spread, but this is marginal added value.

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

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

The description clearly states it returns category-bucketed example questions with tool suggestions, distinguishing it from siblings like ask_pipeworx and compare_entities by positioning it as the onboarding entry point.

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 the agent doesn't know what Pipeworx can do, and explains how to call it with or without a topic, as well as mentioning related meta-tools for further action.

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

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

The description adds useful context beyond annotations: ownership enforcement, row deactivation, and historical availability. 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?

Two concise sentences with the key information front-loaded, no unnecessary words.

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

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

Complete for a simple tool with one parameter, no output schema; covers purpose, ownership, and effects. Minor gap: no mention of potential errors or prerequisites.

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

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

Schema coverage is 100% and the description does not add extra meaning for the 'id' parameter beyond what the schema provides.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

It explains ownership enforcement and the side effect (deactivation vs deletion), but does not explicitly mention when not to use or contrast with 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?

This description goes far beyond the annotations. It explains critical failure semantics: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim, and must not be shown as one.' It also details the meaning of 'unsupported' (we looked and cover no source), the verdict types returned, and the inclusion of a pipeworx:// citation. The readOnlyHint and idempotentHint are consistent with the description — it performs no mutation. The description adds rich context about errors and return behavior that annotations do not cover.

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

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

The description is moderately long but every sentence adds necessary value: trigger phrases, routing logic, verdict list, failure semantics, and the performance benefit. It is front-loaded with the most actionable information ('Use whenever...') and structured naturally from purpose to behavior to caveats. There is no filler or tautology.

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

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

Despite lacking an output schema, the description fully describes the return payload (verdict, actual value with citation, reasoning) and clarifies the meaning of each error state (could_not_verify, unsupported). It also explains the two distinct pipelines and their scope (financial vs. other). Given the tool's complexity, this is a complete and self-contained description that would allow an agent to invoke it correctly without further documentation.

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 baseline is 3. The description repeats the tolerance_pct semantics already present in the schema (e.g., the default, the 0.5–50 range, and the hallucination-detection use case) without adding new parameter-level detail. The claim parameter is also documented in the schema with examples. The description does contextualize parameters within the overall flow, but no additional meaning is added beyond what the schema already provides.

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

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

The description opens with a clear, specific verb-object pair ('validate claim') and immediately defines the tool's role as natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by focusing on issuing a verdict (confirmed, refuted, etc.) and by explicitly describing the two processing paths (SEC EDGAR for financial claims, grounded pipeline for everything else).

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 direct usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the routing logic (which claims go to the structured path vs. grounded pipeline) and notes that the tool replaces 4–6 sequential calls, giving integration context. It does not explicitly name alternative tools or state when NOT to use it (e.g., for subjective or non-factual questions), so it lacks an explicit exclusion clause but still offers strong guidance.

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