Library Of Congress

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a strong safety profile. The description adds valuable context beyond annotations: the default model is free, Anthropic probing requires a BYO API key with direct payment, and the return format is outlined. 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 paragraph of 3 sentences, front-loaded with the core purpose. It covers models, API key, output, and use cases without unnecessary words. Slightly longer than ideal for extreme conciseness, but well-organized and efficient.

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

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

Despite no output schema, the description details the return format (per-model {score, confidence, signals, raw_response} + combined view) and the scoring range (0-100). It covers use cases and required/optional parameters. Not fully exhaustive (e.g., what 'signals' contains), but sufficient for an audit tool with rich annotations.

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

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

Schema coverage is 100% with good descriptions, so baseline is 3. The description adds meaning by explaining that the _apiKey is only needed when 'anthropic' is in models and that it's passed directly to Anthropic, and it clarifies the default model behavior. 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 clearly states the verb ('Probe'), the resource ('one or more LLMs'), and the output ('score visibility (0-100) per model'). It also specifies the default model and the optional Anthropic integration, making the tool's purpose highly specific and distinguishable from siblings like 'scan_competitor_ai_presence'.

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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not provide explicit guidance on when not to use this tool or how it compares to alternatives like 'scan_competitor_ai_presence' or 'compare_entities'. The context is clear but lacks exclusions or alternative 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, openWorldHint, idempotentHint, and destructiveHint. The description adds context about routing to other tools and returning citations without contradicting annotations. It doesn't detail rate limits or failure modes, but the existing annotations cover the key behavioral traits.

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 with the key message 'PREFER OVER WEB SEARCH' and structured with clear usage guidance, examples, and explicit alternatives. 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?

Given the complexity (6 parameters, no output schema, rich annotations), the description provides sufficient context: what the tool does, when to use, and how it compares to siblings. It mentions citations but doesn't detail output format extensively, but the examples and overall guidance are complete enough for an agent.

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

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

Schema description coverage is 100% for all 6 parameters (including aliases for 'question'). The description does not add further parameter-level meaning beyond examples, but the schema itself provides adequate descriptions. 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?

Clearly states the tool routes questions to a vast collection of verified sources and returns structured answers with citations. Distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and contrasts with web search.

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 to prefer this tool over web search for factual questions, provides example query types, and tells when to step up to alternatives (e.g., ask_pipeworx_grounded for single authoritative answer, deep_research for broad multi-part questions).

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

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

Beyond annotations (readOnlyHint, etc.), description details behavior: returns {answer, evidence, confidence, source, fetched_at, refusal_reason} on success or explicit refusals. Also mentions extra LLM call cost. No contradiction with annotations.

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

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

Front-loaded with purpose, then concise details on routing, return format, and usage guidance. Every sentence is informative 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 complexity (no output schema, multiple refusal reasons), description fully explains behavior, parameters, and use cases. Agent can correctly select and invoke without 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%; description adds no new parameter meaning beyond noting the 'question' parameter and its aliases, which is already in schema. Baseline 3 is appropriate since schema suffices.

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

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

Clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' with specific verb+resource (answer extraction). Distinct from sibling 'ask_pipeworx' by explaining same routing but grounded extraction without invention.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and provides exclusion: 'prefer ask_pipeworx for casual lookups.' Also notes cost trade-off.

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

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

Annotations already indicate read/indempotent/non-destructive. Description adds extensive behavioral context: fan-out patterns, handling of low-confidence matches, closed markets, wide spreads, cancellation rules, and resolution-rule risk. No contradiction with annotations.

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

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

The description is comprehensive but verbose, containing multiple paragraphs with repeated examples and detours (e.g., resolution-rule risk). While well-structured with headings, it could be trimmed to front-load key points without losing clarity.

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, the description covers input formats, behavioral safety, response shapes, evidence types, resolver contract, parent event extraction, and edge cases. No output schema, but the response shape is described adequately.

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

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

Schema covers 100% of parameters with descriptions. Description adds significant value: explains market_input variability (slug, URL, text), depth options with examples, and include_raw with detailed usage guidance (e.g., 'keeps responses under ~20KB').

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output, and distinguishes from siblings by enumerating use cases like 'should I bet on X' vs. other tools like polymarket_edges.

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

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

Explicitly suggests use cases ('Use for ...'), but does not mention when not to use or compare directly with sibling tools. However, the context is clear enough for an agent to select this tool for research-oriented betting queries.

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 readOnly, openWorld, idempotent, non-destructive. Description adds specifics: for company - latest 10-K financials with proper fiscal year handling; for drug - adverse event counts, FDA approvals, trial counts; sorted results; citation URIs. No contradictions.

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

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

Description is dense with information but front-loads key trigger phrases and usage intent. Every sentence adds value; however, the length could be slightly trimmed without losing clarity.

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 two entity types with distinct data sources, the description covers what data is pulled, how results are sorted, and output format (paired data with URIs). No output schema is needed because return structure is 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 has 100% coverage with descriptions for both parameters. Description adds meaning: explains type values ('company' pulls financials, 'drug' pulls regulatory data), clarifies values format (tickers/CIKs for company, names for drug), and specifies constraints (2-5 items).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), and differentiates from sequential lookups. The trigger phrases and replacement of 8-15 lookups make 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?

Provides explicit examples of when to use ('Compare X and Y', 'which is bigger', 'rank these companies') and instructs to prefer over sequential single-pack lookups. Lacks explicit when-not-to-use but context implies alternatives are singular lookups.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds details: returns verbatim evidence, confidence, source, fetched_at, stable citations, and explicit gaps for unanswered facets. Discloses that breaking news topics yield empty gaps.

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 critical info (account, alternative). Each sentence adds value, but the description is lengthy; a slightly more concise format could improve scannability.

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

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

Given tool complexity, 2 parameters, and no output schema, the description thoroughly covers functionality, result format, limitations, and relationships to sibling tools. No missing critical context.

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

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

Schema coverage is 100% for both parameters. Description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies that question is natural language for broad/multi-part topics.

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

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

The description clearly identifies the tool as performing grounded multi-source research across structured data sources, decomposing questions into facets with parallel tool routing. It explicitly distinguishes from sibling tools like ask_pipeworx for single lookups and advises against use for breaking news.

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

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

Provides explicit when-to-use (broad/multi-part over structured data) and when-not-to-use (breaking news, paywalled 'thorough' depth). Specifies alternatives (ask_pipeworx) and required account with free signup.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, read-only behavior. The description adds valuable behavioral context beyond annotations: it states that the tool returns the top-N most relevant tools with full input schemas and examples, and that results are 'ready to call directly, no second schema lookup needed.' This helps the agent understand the return format and efficiency. 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 a single block of text with 4-5 sentences. It is front-loaded with purpose and usage, then provides behavioral details. It could be more concise (e.g., the list of domains is lengthy), but every sentence adds value and there is no fluff. The structure is logical.

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

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

Given the tool's low complexity (one required param, no nested objects, no output schema), the description is largely complete. It explains the tool's purpose, usage, and return format (top-N tools with names, descriptions, schemas). It does not specify what determines 'top-N' or pagination, but these are minor omissions. Annotations cover safety. Overall, sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%—all 6 parameters are described in the schema. The description adds value by providing concrete example queries ('look up FDA drug approvals', 'analyze housing market trends') and listing example domains, which help the agent craft effective inputs. While the schema already covers param descriptions, the examples in the description enhance semantic clarity.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses specific verbs (find, discover, browse, search) and specifies the resource (tools). It distinguishes from siblings by positioning itself as a tool for exploring the available toolset, with explicit instruction to 'call this FIRST' to see options, unlike sibling tools that perform specific tasks.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a list of domains. It also states when not to use it for a single answer: 'Call this FIRST when you have many tools and want to see the option set (not just one answer).' This is excellent differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes further by detailing the fan-out across multiple sources (SEC, XBRL, USPTO, news, GLEIF) and listing exact return fields. It also transparently discloses that USPTO may soft-fail due to API sunset, adding valuable 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 dense but well-organized, starting with example triggers and a clear purpose statement. It is slightly verbose in listing return fields inline, but still effective. Minor trim could improve conciseness, but overall structure is 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?

Given the tool's complexity (multiple sources, numerous return fields, no output schema), the description is highly complete. It details each data source, what it returns, and caveats (USPTO soft-fail). It also addresses input constraints and provides alternative tool guidance. 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?

The input schema already provides descriptions for both parameters with 100% coverage. The description adds extra clarity by specifying the format ('AAPL' or zero-padded CIK), explaining that names are not supported, and pointing to an alternative tool. This is helpful but not strictly necessary given 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 opens with concrete example queries and explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' This clearly defines the tool's purpose and distinguishes it from siblings like resolve_entity (names not supported).

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' providing clear when-to-use advice. It also notes names are not supported and directs users to resolve_entity first, offering an alternative.

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

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

Description states deletion, aligning with destructiveHint=true and idempotentHint=true. Adds context about clearing sensitive data beyond annotations.

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

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

Two sentences, front-loaded purpose, every sentence adds value. 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?

Simple tool with one param, no output schema. Description covers usage, purpose, and relationships to siblings. Fully adequate.

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

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

Only one parameter 'key' with 100% schema coverage. Description doesn't add beyond schema but implicitly connects to the purpose.

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

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

Clear verb+resource: 'Delete a previously stored memory by key.' Distinguishes from siblings remember and recall.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Suggests pairing with related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also mentions the output is a 'single text blob ready to drop at site-root/llms.txt', which 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?

Three sentences covering purpose, process, and use cases – no wasted words. Front-loaded with the main action, every sentence earns its place.

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

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

Simple tool with 2 params, no output schema. Description covers input, process, and output format. Missing error scenarios or limitations (e.g., what if URL is unreachable), but generally complete for the task.

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 no additional meaning beyond what the schema already provides (e.g., 'Full URL' and 'default 25, max 50' are already in 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 states a specific verb ('Generate') and resource ('production-ready llms.txt file for any URL'), clearly distinguishing it from sibling tools like 'scan_competitor_ai_presence' or 'ai_visibility_check' which serve different functions.

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 ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), but does not mention when not to use it or alternatives among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so safety is clear. The description adds value by specifying the returned fields and that subscriptions are scoped to the caller, providing 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 sentences that front-load the purpose and returns, followed by usage guidance. Every sentence earns its place with no redundancy or fluff.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It covers what the tool does, what it returns, and when to use it, leaving no essential gaps.

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

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

Schema description coverage is 100%, meaning the parameter include_inactive is already well-documented in the schema. The description's mention of 'active subscriptions' implicitly confirms the default, but adds no 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 the tool lists the caller's active subscriptions and enumerates the fields returned (id, type, etc.). It distinguishes itself from sibling tools subscribe and unsubscribe by focusing on listing existing 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?

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This directly guides the agent toward appropriate scenarios, contrasting with sibling tools for creation and cancellation.

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 important behavioral traits beyond the annotations: rate-limited to 5 per identifier per day, free usage no quota cost, and that the team reads digests daily. These are critical for the agent to manage usage expectations. No contradiction with annotations.

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

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

The description is concise (4 sentences) and front-loads the core purpose. Each sentence adds useful information without redundancy. It could be slightly shorter, but it is 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?

The description covers usage, parameters, and limitations. There is no output schema, so return values are not needed. Minor gap: no mention of what the agent should expect after sending (e.g., confirmation or error handling), but for a simple feedback tool this is acceptable.

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 value by explaining the enum values with examples and providing formatting guidelines for the message (be specific, 1-2 sentences, 2000 chars max). This helps the agent craft appropriate input.

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: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It specifies the types and provides context for each, distinguishing it from sibling tools that are query or research oriented.

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 tells when to use the tool (bug, feature, data_gap, praise) and provides guidance on how to describe issues (in terms of Pipeworx tools/packs). It does not include explicit 'when not to use', but the positive guidance is clear and sufficient for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which 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 concise (3-4 sentences) with front-loaded purpose. Every sentence provides distinct value: purpose, use cases, data source, caching. 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?

No output schema exists, but the description clearly states what is returned (top tools, packs, call volume). Combined with strong annotations and schema, the information is sufficient for a read-only trending 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 is 3. The description adds context for the 'window' parameter: shorter windows show 'hot right now', longer show 'steady-state demand', enhancing the enum choices.

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 trending data (top tools, packs, call volume) from a specific source (Pipeworx agent calls). It distinguishes itself from siblings like 'discover_tools' (which likely lists available tools) and 'ask_pipeworx' (Q&A).

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 (discovering hot data, confirming canonical tools, aligning with agent needs) and contrasts window options (short vs long). However, it does not explicitly compare with sibling tools or state when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: the algorithm (monotonicity violations, partition-sum checks), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check against live CLOB depth. It warns when a trade should not be executed. 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 somewhat lengthy but well-structured: it starts with a requirement note, then explains modes, algorithm details, and output format. Every sentence adds value given the tool's complexity. Slight verbosity in the middle section, but overall appropriate.

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

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

The tool has no output schema, so the description must cover return values. It does this thoroughly: opportunities[] with gap_pp, suggested_trade, reasoning; partition_check with fields; fill check results. It also covers edge cases like calling with no args fails, partition filter threshold, and semantic anchor. Complete for a 2-param 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 parameters have descriptions. The tool description adds value beyond the schema by explaining the two modes, providing examples for each parameter (e.g., 'fed-decision-may-2026'), and clarifying that full Polymarket URLs are accepted. This helps the agent understand parameter semantics more deeply.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and specifies that calling with no args fails. The verb is specific ('Find arbitrage opportunities') and the resource is clear (Polymarket). This differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: event for specific markets, topic for cross-event scanning. It explains that the topic mode catches patterns the event mode misses. It also mentions custom sizing should use polymarket_fill_risk instead. However, it does not explicitly state when not to use this tool versus other siblings beyond that one alternative.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral context: detailed model families, response structure including diagnostics, caching strategy (1h KV keyed on knobs), and exclusions (Fed bets). This greatly exceeds the minimum, providing a rich understanding of tool behavior.

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

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

The description is quite verbose, with multiple paragraphs detailing model internals and response structure. While every sentence adds value, the length could be reduced by moving technical details to supplemental documentation. The front-loading of purpose is good, but overall structure lacks conciseness.

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

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

Given the tool has 9 optional parameters, no required fields, and no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and how each parameter affects output. Caching and exclusion logic are covered. It is complete enough for an AI agent to use effectively.

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 each parameter already has a description. The tool description adds context by explaining tradeable-edge knobs and how filtering works (e.g., min_partition_leg_kelly vs. min_kelly). This adds value beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it's built for 'what should I bet on today'. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, missing an opportunity to guide selection.

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

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

The description implies usage for discovering betting opportunities without paging through markets, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings. The context is sufficient for basic use but lacks comparative reasoning.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavioral context: reads snapshots, returns computed trends, explains gaps due to cache-miss, and limits (60-day TTL, snapshot start). No contradiction with annotations.

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

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

The description is front-loaded with the key question and purpose. It is well-structured with clear sections for response format and limits. While somewhat lengthy, 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 no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and includes important limitations (history depth, decay computation). It covers the agent's need for understanding the output and constraints.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by specifying defaults (days=14, window='1wk'), max/clamp ranges, and explaining the purpose of each parameter (lookback, snapshot family). This goes 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 provides edge persistence and decay telemetry from daily snapshots, answering a specific question about edge longevity. It distinguishes from siblings like polymarket_edges by focusing on temporal analysis.

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

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

The description explicitly tells when to use (to understand edge longevity and decay) and implies when not (if only current edges are needed, use polymarket_edges). It provides context on the time-series comparison but could name alternatives more directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and stateless. The description adds valuable behavioral details: walks order-book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, and warns about forced_directional_risk. No contradiction with annotations.

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

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

The description is lengthy but well-structured into three paragraphs: overview, single-market mode, basket mode, and usage guidance. It front-loads the core purpose. Could be slightly more concise, but the complexity justifies the length.

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

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

With no output schema, the description fully details all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). Also explains motivation and risk. No gaps.

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

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

Schema description coverage is 100% with descriptions for all 4 parameters. The description adds context beyond schema: default values for side and size_usd, interpretation of size_usd for buys vs sells, and mode-specific meaning for side (auto-detection for basket). This adds significant 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 uses specific verbs and resources: 'Realizable-vs-theoretical edge check against live CLOB order-book depth', and clearly distinguishes between single-market and basket modes. It contrasts with sibling tools like polymarket_arbitrage by stating it should be used before acting on signals.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why partial fills can convert arb to unhedged position, and gives prerequisite of one required parameter.

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 details behavioral traits: two modes, response structure (leg-by-leg prices, spread in pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains why some pairings yield no arb. This adds context beyond annotations (readOnly, idempotent, etc.) without contradiction.

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

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

The description is lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though some redundancy exists (e.g., repetition of pre-mapped topics). 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 complexity (cross-venue spread with equivalence checks), the description covers modes, response format, safety fields, and edge cases. No output schema exists, but return values are described adequately. Minor missing detail: exact format of spread array or temporal_alignment values.

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

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

Schema coverage is 100% and the description adds significant meaning: it explains each parameter (topic enum values, explicit tickers overriding topic), provides usage examples, and clarifies the dual-mode behavior. This exceeds the baseline for fully described schemas.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains when bet shapes are equivalent. This specificity differentiates it from siblings like polymarket_arbitrage.

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

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

The description explicitly says when to use the tool for spread comparison and warns when not to (compatibility_warning). It implicitly contrasts with other tools by emphasizing equivalence checking, but does not name alternatives directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. Description adds scoping info (identifier-based) but not much 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 succinct (4 sentences) and front-loaded with core function. 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 tool with one optional parameter and clear annotations, the description fully covers behavior, scope, and relationships to siblings.

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 description essentially restates the parameter's purpose (omit to list all keys). Minimal added value beyond schema.

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

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

Description clearly states it retrieves a value saved via remember or lists all keys if omitted. Specific verb 'retrieve' and resource 'saved value' with clear distinction from sibling tools remember and forget.

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

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

Explicitly says to use for looking up context stored earlier and to pair with remember/forget. No explicit 'when not to use' but the context is clear and 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?

The description discloses important behavioral details: it lists returned fields and explains the mark_read parameter's effect. However, the annotation readOnlyHint=true contradicts the described state-modifying behavior when mark_read is set to true. This inconsistency undermines trust and reduces transparency.

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

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

The description is concise (three sentences) and well-structured: first sentence states purpose, second lists key fields, third explains filter parameters and polling. 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?

Without an output schema, the description adequately explains return values (source, citation_uri, raw event payload). It also covers parameter usage and mentions an alternative endpoint. However, it does not specify pagination or error handling, which might be needed for a polling 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?

All 5 parameters have schema descriptions, and the description adds context beyond the schema. For example, it clarifies that mark_read flags events as read and unread_only filters based on read_at being null. The description also explains the interaction between parameters.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies that it returns the most recent alerts with source, citation_uri, and raw payload. It also distinguishes itself by mentioning filtering capabilities, which no sibling tool covers.

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 usage guidance: it mentions that polls work fine and points to an alternative endpoint for scripts/dashboards, implying this tool is for interactive use. It also explains how to use parameters like mark_read and unread_only to manage read state. However, it does not explicitly exclude any alternatives or scenarios.

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 significant behavioral details: fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and output structure. No contradictions with annotations.

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

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

The description is slightly long but every sentence adds value. It starts with query examples, then describes behavior, fallbacks, and output. Could be trimmed slightly but is well-structured and front-loaded.

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

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

Given the tool's complexity (multiple sources, fallback logic, parameters with enum), the description covers required parameters (100% schema coverage), describes output structure despite no output schema, and mentions known issues (USPTO sunset). It is comprehensive.

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

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

Schema coverage is 100%, baseline 3. Description adds value by providing examples for `since` (ISO date or relative shorthand), clarifying `value` accepts ticker or CIK, and giving usage advice for `since` ('Use "30d" or "1m" for typical monitoring').

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 provides a change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) with specific query examples. It distinguishes itself from the sibling tool 'entity_profile' by advising to use that for static profiles.

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 examples of when to use the tool (e.g., 'what's new with X') and explicitly recommends the sibling tool 'entity_profile' for static profiles. It lacks explicit when-not-to-use scenarios but the alternative is well-defined.

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

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

Annotations already provide idempotentHint=true, and the description adds behavioral context like scoping by identifier and session vs persistent memory. However, it does not clarify overwrite behavior on existing keys, which could be inferred from idempotency but is not explicit.

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 at 4 sentences, front-loaded with the core purpose, and structured logically: purpose, usage scenario, storage details, and tool relationships. No redundant information.

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

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

For a simple key-value memory tool with no output schema and good annotations, the description covers essential aspects: what data to store, when to use, and persistence behavior. It could mention maximum key/value length or duplicate handling, but overall 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 describes both parameters with 100% coverage, but the description adds value by giving example key patterns like 'subject_property' and clarifying that value is 'any text — findings, addresses, preferences, notes', which enriches 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's purpose: 'Save data the agent will need to reuse later' and provides concrete examples of what to store. It distinguishes itself from sibling tools 'recall' and 'forget' by mentioning them as partners.

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 ('when you discover something worth carrying forward') and provides context on persistence (authenticated vs anonymous sessions). Mentioning pairing with recall and forget gives clear guidance on when not to use this tool.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context by explaining that 'each call cascades through several lookup endpoints' and details the specific return data (ticker, CIK, RxCUI, citation URIs) and auto-disambiguation for company names. This goes beyond annotation requirements.

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

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

The description is well-structured: it opens with example queries, states the core purpose, gives usage instruction, then details supported types. Every sentence adds value, but the length (≈150 words) could be slightly trimmed without loss of clarity. Still effective and front-loaded.

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

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

Given the tool's simplicity (2 parameters, no output schema, full annotations), the description is sufficiently complete. It explains return values, internal cascade behavior, and input variations. Minor gaps: no mention of error handling or rate limits, but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description enhances meaning by providing concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and clarifying the interpretation of the 'value' parameter, such as auto-disambiguation for company names. This adds value beyond enum labels.

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

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

The description starts with concrete examples ('What's the ticker for…') and explicitly states it resolves user-spoken names to canonical identifiers needed by other tools. It clearly distinguishes from siblings by specifying supported entity types and outputs (ticker, CIK, RxCUI, etc.), making the tool's purpose unambiguous.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' giving clear prioritization. It notes that it replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it or compare to sibling tools like 'entity_profile' or 'compare_entities', which could be alternatives in some workflows.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds behavioral details: it probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

The description is two sentences: first sentence states the action and process, second sentence provides use case and expected output. Every sentence is essential, no redundancy.

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

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

No output schema exists, but the description specifies the return format (ranked list with score, confidence, signal density). All parameters are described, and behavioral context from annotations is sufficient. The tool fits well with sibling tools like 'ai_visibility_check'.

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

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

Schema description coverage is 100%, but the description adds value beyond schema by explaining that the first entity is treated as the subject, that models default to 'workers-ai', and that '_apiKey' is conditionally required. It also explains the purpose of 'context' for disambiguation.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, specifies verbs ('compare', 'probes', 'ranks', 'surfaces'), and differentiates from sibling tools like 'ai_visibility_check' by focusing on multi-entity comparison with ranking.

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 concrete use case ('competitive AI-marketing audits: does Claude know about us as well as our competitors?') and implies when to use it (multi-entity comparison). However, it does not explicitly mention when not to use it or suggest alternatives like 'ai_visibility_check' for single entities.

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

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

Annotations already indicate safe, idempotent read. The description adds critical behavioral details: partial failures, 5-30s delay for bundlephobia first measurement, and graceful degradation with sources_failed listed. 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 well-structured and front-loaded with the main purpose. While it contains many details, they are all relevant. Could be slightly more concise but still effective.

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

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

Despite no output schema, the description lists all return fields and explains failure modes. Combined with rich annotations, the agent has complete context to 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% and both parameters have clear descriptions. The tool description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it's a composite check for npm packages across deps.dev and bundlephobia. It uses specific verbs and resource, and distinctly stands out from sibling tools which are unrelated to dependency analysis.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, or size. Also specifies NPM-only in v1 and points to deps.dev:version for other ecosystems, providing clear exclusion criteria.

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, making the non-destructive nature clear. The description adds specific technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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 a single paragraph with a clear flow: action, usage scenario, examples, technical details, and limitations. Each sentence adds value, and the key information is front-loaded.

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

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

Despite no output schema, the description mentions return values: 'top-N passages with character offsets and similarity scores'. Combined with schema covering all params, annotations for safety, and description covering behavior, the tool definition is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real-world examples (SEC 10-K, article) for the text parameter, natural-language query examples, and explains the limit parameter implicitly. This extra context raises the score.

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

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

The description clearly states the tool performs semantic search inside a provided record, using the verb 'search' and specific resource 'inside a fetched record'. It distinguishes from siblings like ask_pipeworx_grounded by focusing on local parsing of already-fetched text.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded for grounding. This provides clear when-to-use and alternative 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?

The description adds behavioral details beyond annotations: requires OAuth account, SMS rate limit (10/day), webhook auto-disable after 10 failures, and signing secret once. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the purpose. Every sentence adds value, though it is slightly lengthy. Efficient overall.

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

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

Given no output schema, the description explains the return value (subscription ID). All parameters and their usage are thoroughly explained, making the tool fully understandable for an AI agent.

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

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

Even with 100% schema coverage, the description adds significant value by providing concrete examples for each subscription type and delivery channel, including specific parameter formats and constraints (e.g., phone verification, email pattern).

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns the new subscription ID, and distinguishes itself from sibling tools like unsubscribe 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?

The description provides explicit context for when to use (creating subscriptions), prerequisites (Pipeworx OAuth account), and examples for supported types. It does not explicitly state when not to use 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?

Annotations already declare readOnly, idempotent, etc. Description adds context about output structure (category-bucketed, live catalog) and argument effects, providing value beyond annotations. No contradiction.

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

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

Description is front-loaded with trigger phrases and purpose, well-structured with examples, return format, usage, and invocation. Every sentence is informative and earns its place despite moderate length.

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

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

Given the tool's role as onboarding entry point with one optional parameter and no output schema, the description is complete: explains what it returns, when to use, how to use, and gives examples. 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% and description adds meaning beyond schema: explains that omitting topic gives full spread, while passing a topic focuses on a category (e.g., 'finance', 'pharma'). This enriches the agent's understanding of parameter behavior.

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

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

The description clearly states the tool returns category-bucketed example questions about Pipeworx's capabilities, using specific verbs like 'Returns category-bucketed example questions'. It distinguishes from siblings like ask_pipeworx by labeling itself 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?

Explicit guidance on when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains argument behavior: no args for full spread, topic for focus.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds: ownership enforcement and that the row is deactivated not deleted, preserving history. No contradictions.

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

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

Three sentences, each adding key information. No wasted words. Front-loaded with the action.

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 ownership, soft delete, and relation to recent_alerts. With simple parameter and good annotations, it's mostly complete. Minor gap: no explicit mention of idempotency or double-cancel behavior, but that's hinted by annotation.

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

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

Schema coverage is 100% for the single parameter 'id'. The description simply references the id without adding extra meaning, so baseline 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id.' which is a specific verb+resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by describing the action and outcome.

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 important context: ownership enforcement ('you can only cancel your own subscriptions') and behavioral consequence (soft delete, not hard delete). It implies when to use this over delete-like tools, though 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes further by revealing the underlying data source (SEC EDGAR + XBRL), the return format (verdict with categories, structured form, citation, delta), and the efficiency gain (replaces 4–6 calls). 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 front-loaded with common query patterns, followed by usage guidance, scope, and return details. Every sentence serves a purpose with no filler. Despite length, it remains efficient and well-structured.

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

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

With one parameter, no output schema, and rich annotations, the description covers all necessary context: return value details, domain limitations, and behavioral aspects. It fully equips the agent to decide when and how to use the 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% for the single 'claim' parameter, which includes examples. The description reinforces that the claim is a natural-language string and gives implicit guidance on format (e.g., 'Apple's FY2024 revenue was $400 billion'). 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 begins with explicit natural-language trigger phrases ('Is it true that...', 'fact check', etc.) and clearly states the tool's purpose: claim verification against authoritative sources. It differentiates from siblings by mentioning it replaces 4–6 sequential calls, which is a strong distinguishing feature.

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 whenever the agent needs to check whether something a user said is factually correct.' It also delineates the supported domain (company-financial claims for public US companies) and the authoritative sources (SEC EDGAR + XBRL), providing clear usage boundaries.

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