Box

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context: default free model, BYO API key with direct billing to Anthropic, and the return shape (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond the structured hints without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds value: what it does, cost/model details, and return/use cases. No waste.

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 shape and covers inputs, cost, and use cases. The tool's complexity is low (4 params, 1 required), and the description provides sufficient context for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema documents all parameters well. The description adds cost semantics for _apiKey (you pay Anthropic directly) and clarifies the default model behavior, which adds meaning beyond the schema's parameter 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 probes LLMs for knowledge about an entity and produces a 0-100 visibility score per model. It specifies the resource (business/brand/product/topic) and the verb (probe/score), distinguishing it from sibling tools like ask_pipeworx (which likely queries Pipeworx data) and 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?

Explicit use cases are provided ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use the tool. It does not explicitly name alternatives or exclusion criteria, but the use-case framing offers sufficient 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 mark the tool as read-only, idempotent, and open-world, so the bar is lower here. The description adds useful behavioral context beyond annotations: it routes questions to one of 5,767 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not detail failure modes or source gaps, but the read-only, low-risk profile makes that less critical.

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 densely packed with useful information: preference rule, capability, trigger phrases, examples, and alternatives. It is front-loaded with the key routing behavior and avoids generic filler, though the category list and examples are extensive enough that it is not maximally 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?

For a read-only router with no output schema, the description adequately explains the return format, the breadth of sources, and when to choose alternative tools. It gives enough context for an agent to decide whether to invoke ask_pipeworx and what to expect back, though it does not describe edge cases such as questions with no matching 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% and the schema already documents the question parameter plus its five aliases, so the description does not need to repeat parameter-level detail. The description's examples and trigger phrases add useful context about what kinds of questions to pass, but they do not add new constraints or semantics 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 defines ask_pipeworx as a router that answers factual questions using authoritative structured data, listing concrete domains and explicitly distinguishing it from web search and sibling tools like ask_pipeworx_grounded and deep_research. It also states the output shape: a structured answer with stable pipeworx:// citation URIs.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with concrete trigger phrases and examples. It also names alternatives with conditions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions, and notes breaking-news is already handled.

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

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

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description transparently discloses the experimental nature: candidate routing improvements are enabled live whenever under test, and currently no candidate is active, so it matches ask_pipeworx exactly. It also clarifies fallback behavior, stating this is a full working router with no fallback to another tool.

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 longer than the typical tool description, but each sentence serves a purpose: establishing the beta relationship, explaining the current inactive-candidate state, and clarifying usage. The retirement date is extra detail but supports the claim that no candidate is currently active, so the slight length is justified.

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 what the tool does, its relationship to ask_pipeworx, its current state, and how it behaves experimentally. It references the same response shape as ask_pipeworx, which helps with the missing output schema, but it does not elaborate on what happens if a candidate fails or how the response might differ during a live test. Still, the description is sufficient for an agent to invoke it correctly in most cases.

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

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

The input schema already provides 100% parameter coverage, including aliases for the question parameter. The description says the tool accepts the same arguments as ask_pipeworx but does not add further semantic detail beyond what the schema already documents. A baseline score of 3 is appropriate because the schema carries the parameter documentation burden and the description offers no additional parameter-level insight.

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 a beta version of ask_pipeworx: a universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable sibling by explicitly naming ask_pipeworx and describing the experimental routing difference, as well as clarifying it is a full working router.

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

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

The description gives an explicit usage directive: use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It does not explicitly describe when to use ask_pipeworx_grounded or the stable router instead, but the comparison with ask_pipeworx is clear enough for an agent to select this tool for experimental routing.

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

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

The description explains the grounded behavior beyond annotations: it uses only tool-result content, returns structured success and refusal payloads, and enumerates possible refusal reasons. It also discloses the extra LLM call cost, which is not visible in annotations. No contradiction with the readOnly/openWorld/idempotent hints exists.

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

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

The description is dense but every sentence earns its place: it explains the mechanism, the exact return and refusal shapes, the usage context, and the trade-off versus the sibling tool. The output payload is spelled out because there is no output schema, making the length justified rather than padded.

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

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

Given there is no output schema, the description compensates fully by specifying the success payload, refusal payload, refusal reasons, and the extra-cost behavior. It also distinguishes itself from ask_pipeworx and covers the operational context an agent needs 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?

The input schema already fully documents the natural-language question parameter and all aliases, so description-level parameter detail is unnecessary. Baseline 3 is appropriate because the schema coverage is complete and the description implicitly clarifies that the question is fed into the routing/grounded pipeline.

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 a hallucination-resistant answer mode that routes through Pipeworx tools and extracts answers only from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded, evidence-based responses versus casual 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?

It explicitly states when to use the tool: high-stakes reads, quoted/cited/acted-on answers, and domains like financial verdicts, legal claims, medical lookups, or public statements. It also gives a clear directive to prefer ask_pipeworx for casual lookups, providing both positive and negative 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: resolver confidence levels (high/medium/low/none), low-confidence short-circuit behavior, market_closed_or_inactive status, illiquid_wide_spread warnings, parent-event extraction, news fallback behavior, and cancellation-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 long but exceptionally well-structured with clear section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) and a front-loaded one-sentence summary. Every section contributes functional knowledge, so the length is justified. However, it is dense enough that conciseness suffers slightly, preventing a 5.

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 carries the full burden of explaining return shapes, and it does so comprehensively: result.market, result.analysis, result.evidence, resolver contract fields, parent_event structure, news fallback fields, and edge-case statuses. It also covers safety precautions and cancellation-rule risk. This is a complete specification 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?

The input schema already provides 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw). The description adds some context about the market input formats (slug, URL, question text) and mentions depth/raw in passing, but it does not meaningfully elaborate beyond the schema's own parameter documentation. 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the tool's scope (resolving, classifying, fanning out, returning evidence) and explicitly lists three use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which distinguishes it from sibling tools like polymarket_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?

The description explicitly states when to use the tool with concrete example queries and gives detailed fan-out examples for various bet categories. However, it does not explicitly name alternatives or state when not to use this tool in favor of a sibling, so it lacks the exclusionary guidance that would push it to a 5.

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 idempotentHint=true, so the safety profile is covered. The description adds behavioral detail by enumerating the exact return fields (id, name, size, description, timestamps, parent folder, shared link URL, extension), which helps the agent anticipate the tool's output without needing an output schema.

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 compact: two sentences that front-load the action and resource, then list return fields and usage context. There is no fluff or redundancy, every word 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?

For a simple one-parameter tool with rich annotations and a complete schema, the description is fully adequate. It explains what the tool does, when to use it, and what output to expect, leaving no critical gaps for the agent to make a correct invocation.

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

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

The schema description for file_id ('The Box file id of the file to inspect') is clear and complete, achieving 100% coverage. The main description adds only a slight clarification that the file is a single Box file. Since the schema already documents the parameter, the description provides minimal additional semantic value, warranting the baseline score of 3.

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

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

The description clearly states the tool's function: 'Get full metadata for a single Box (cloud storage) file by its file id.' This specific verb+resource combination distinguishes it from siblings like box_get_file_text (content extraction) and box_list_folder (multiple files). The scope is explicitly limited to a single file via ID.

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 usage context: 'Use after listing or searching to inspect one document.' This tells the agent when to invoke the tool without listing alternatives. While it doesn't explicitly name exclusions, the context (e.g., after listing/searching) and the sibling names make the differentiation 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 provide safety traits (read-only, idempotent, non-destructive, open-world). The description adds valuable behavioral details beyond that: binary files return 'unreadable bytes', content is capped at ~100,000 characters, and truncation is flagged. This goes beyond the structured 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 that lead with the core action and then cover boundary conditions (binary formats, truncation) without wasted words. Every sentence adds value, and the structure is 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?

This is a simple single-parameter tool with strong annotations and a complete schema. The description covers scope, limitations, and truncation behavior, making it fully adequate for an agent to use correctly without an output schema or more complex context.

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

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

The input schema fully documents the only parameter (`file_id`) with a clear description, so schema coverage is 100%. The tool description barely adds additional meaning beyond restating 'by its file id', which meets the baseline but does not elevate it.

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

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

The description uses a specific verb-resource pair ('Download and return the text content of a Box file') and clearly identifies the input required (file id). It also distinguishes itself from the sibling `box_get_file` by focusing on text extraction and noting binary file limitations.

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

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

The description explicitly states the ideal use case ('Best for plain-text, Markdown, CSV, and other text documents') and warns against binary formats, which is clear when-to-use guidance. It does not name an alternative tool directly, but the context is sufficient for an agent to choose appropriately.

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, so the safety profile is known. The description adds value by specifying the exact output fields and that storage amounts are in bytes, providing expectations without contradicting the annotations.

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

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

The description is exactly two sentences: the first states the action and output, the second gives practical use cases. There is no extraneous information, and the most important 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?

With no parameters, a detailed output schema is absent, but the description compensates by listing the return fields and units. Combined with forceful annotations and simple scope, the tool is sufficiently contextualized for correct invocation.

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

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

The input schema has zero parameters, so there is nothing for the description to explain. The baseline score of 4 applies, and the description confirms the tool takes no input by not mentioning any arguments.

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 the specific verb 'Get' with the resource 'the signed-in Box user's profile' and enumerates exact fields (id, name, login email, storage space). This distinguishes it from sibling tools like box_get_file and box_list_folder, 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 explicitly suggests two use cases: 'identify the connected account' and 'report storage usage.' While it does not mention when not to use this tool or name alternatives, the context is clear enough for an agent to select it appropriately.

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, so safety is covered. The description adds valuable behavioral context beyond annotations by specifying the return fields: "Returns each item's id, type (file or folder), name, size in bytes, and last-modified time." It also clarifies the default behavior for omitted folder_id, which aids the agent in anticipating output.

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 front-loaded. The first sentence states the core action, the second explains parameter usage, and the third provides a use case. 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, read-only list tool with two well-described parameters and no output schema, the description covers everything needed: purpose, parameter behavior, return format, and usage context. Annotations cover safety, so the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for both parameters (folder_id and limit), so the schema already documents their meanings. The description reinforces folder_id semantics with "Pass a folder id, or omit it to list the root folder ('0')" but adds little new information beyond the schema, warranting the baseline 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's function: "List the files and subfolders inside a Box (enterprise cloud storage) folder." It also specifies the scope (folder id or root) and distinguishes it from sibling tools like box_get_file or box_search by focusing on browsing folder contents.

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 usage context: "Use to browse a user's Box documents and files." It doesn't explicitly name alternatives or exclusions, but the read-only browsing purpose is evident, and the sibling tool names suggest distinctions (e.g., box_get_file for retrieving a specific file).

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 this as read-only, idempotent, and open-world. The description adds value by disclosing that it searches both names and content, and by specifying the return fields (id, type, name, size, and last-modified time), which annotations do not cover. It does not contradict 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 two sentences long, front-loaded with the core purpose, and every sentence adds value: purpose, optional filter, return fields, and usage. No redundant or filler content.

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

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

Despite having no output schema, the description covers the essential return fields. It also mentions the optional type filter and the search scope (names and content), which together provide a complete picture for a search tool. The default limit is in the schema, so it doesn't need to be repeated.

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 the parameters are fully documented. The description adds little beyond restating the type filter ('Optionally restrict to only files or only folders') and does not provide additional semantics for query or limit beyond what the schema already states.

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

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

The description clearly states the tool's function: 'Search a user's Box (cloud storage) account for files and folders matching a query string across names and content.' It uses a specific verb (search), specifies the resource (Box account), and distinguishes it from sibling tools like box_list_folder and box_get_file by emphasizing keyword search across names and content.

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 usage context with 'Use to find documents by keyword,' which implies the intended scenario for this tool. However, it does not explicitly mention alternatives or when NOT to use it, falling short of a 5.

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 destructiveHint, reducing the burden, but the description goes beyond them by disclosing specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and the return of paired data plus citation URIs. This adds significant behavioral detail without contradicting any 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 but well-structured, starting with trigger phrases and then detailing behavior by type. Every sentence contributes useful information, though the 'Replaces 8–15 sequential lookups' line is somewhat promotional and the examples could be 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 no output schema, the description compensates well by explaining what data is returned, how results are sorted, and that citations are included. It covers both entity types, parameter constraints, and the key advantage of parallel execution, making it complete for an agent to select 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%, so parameters are already documented, but the description adds meaningful semantics by explaining what each type actually retrieves (company: 10-K financials; drug: FAERS counts, FDA approvals, trials). This goes beyond the schema's enum labels and enriches parameter understanding.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with explicit trigger phrases like 'X vs Y' and 'rank these companies.' It also differentiates itself from sequential single-entity lookups, making its purpose unambiguous and distinct from sibling tools such as entity_profile.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool when comparing entities, and provides clear context for when to use it (comparing companies/drugs). However, it doesn't name alternative sibling tools or state explicit when-not-to-use conditions, so it stops short of a full usage guide.

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 non-obvious behavior: account and paid-plan requirements, latency ranges, gaps[] never invented, fetchable citation_uri semantics, hop/contradictions fields, and semantic excerpting. There is no conflict with 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?

Dense and front-loaded: account requirement and fallback tool come first, then core functionality, then routing guidance, then mechanics. It is long and mentions ask_pipeworx in three separate routing conditions, but all are distinct; the main cost is scannability rather than 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?

With no output schema, the description fully explains the return packet—verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]—plus authentication, cost, latency, and scope. An agent has enough to decide whether, when, and how to call this tool.

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

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

Schema coverage is 100% with detailed enum descriptions, so the baseline is 3. The description adds value beyond the schema by explaining per-depth latency expectations, the paid constraint on 'thorough', and the behavioral implications of depth choices for multi-step questions.

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

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

States a specific operation: grounded multi-source research across 1,506 STRUCTURED data sources, decomposing questions into facets and routing them to 5,767 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data; use ask_pipeworx instead for single lookups, breaking/current-news topics, or when not signed in. It directly names alternative tools and the conditions that select them.

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. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and notes that results are 'ready to call directly, no second schema lookup needed.' These details go beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the main purpose. The list of domains is long but serves as useful examples for the query parameter. It is not overly verbose and each sentence earns its place, though the domain list could be trimmed for 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 its moderate complexity (6 parameters, many aliases) and no output schema, the description covers essential aspects: what it does, when to use it, what it returns, and that results include schemas. It lacks explicit limitations (e.g., max limit 50) but the schema covers that. Overall, it is sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning by listing example domains (e.g., 'SEC filings, financials, revenue, profit') that a user might include in the query. It also clarifies the 'top-N' behavior, which relates to the 'limit' parameter, adding semantic value beyond pure schema facts.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.), making it unambiguous. It also distinguishes itself from siblings by positioning itself as a discovery tool: 'Call this FIRST when you have many tools available and want to see the option set.'

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 when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies a use case (option set exploration) but does not explicitly state when not to use it or name alternatives, hence a 4.

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: the soft-fail on USPTO patents, the meaning of empty sections ('real no data, not a bug'), the resolved:false return for private companies, and the parallel call nature. This goes well beyond what annotations provide.

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

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

The description is long but densely packed with essential details and follows a logical sequence (purpose → usage → sources → return structure → edge cases). Every sentence carries operational meaning, though it could be split into clearer bullets. Slight redundancy exists (e.g., repeating the 'one parallel call' concept), but overall it's 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?

With no output schema, the description carries the full burden of return semantics. It enumerates every returned section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used/failed) and explains edge cases like empty sections and private companies. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds value by clarifying that 'type' accepts both values interchangeably and that 'value' can be a ticker, CIK, or name, reinforcing the enum and the input format. This is helpful but not transforming—hence 4 rather than 5.

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 ('full cross-source profile') and resource ('US public company'), and clearly distinguishes itself from single-pack lookups. It also lists the exact sources fanned out, making the scope unambiguous even without inspecting sibling schemas.

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 instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a clear when-to-use directive. It also covers edge cases (private companies, no-data sections) so the agent knows expected behavior in those situations.

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 destructiveHint=true and idempotentHint=true, so the safety profile is clear. The description adds minimal behavioral context ('by key', 'previously stored') but does not elaborate on side effects or permanence, which the annotations sufficiently 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 two sentences: the first states the core action, the second gives usage guidance and related tools. No filler or redundant information exists, making it highly efficient.

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

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

For a simple destructive tool with one parameter and no output schema, the description fully covers purpose, usage timing, and integration with sibling tools. Annotations handle safety concerns, so nothing essential is missing.

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

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

The schema fully documents the single 'key' parameter with 'Memory key to delete.' The main description repeats 'by key' without adding new semantics. With 100% schema coverage, no additional parameter information is needed.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' This distinguishes it from sibling tools like remember (store) and recall (retrieve), making the tool's function 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?

It explicitly provides use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related tools to pair with, offering clear guidance on when to invoke 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 disclose read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful process context: it fetches the page, extracts title/description/key links, emits standard markdown, and returns a text blob ready for site-root placement. 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 three sentences long, front-loaded with the primary purpose, and every sentence adds value: what it does, how it works, and when to use it. No filler or redundancy.

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

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

For a tool with only two parameters and no output schema, the description covers the full workflow, the output format, and the intended use cases. Annotations handle the safety profile, so the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, with both parameters (url and max_links) already well-described in the schema. The description does not add any additional parameter-specific details, but it does reinforce that the tool works for 'any URL'. This meets the baseline for high schema coverage without requiring compensation.

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 action ('Generate a production-ready llms.txt file for any URL') followed by a clear explanation of the process and output. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than visibility auditing, and the use cases further clarify its unique role.

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 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'), which gives clear context for when to use it. It does not explicitly name alternative tools or exclusions, but the use cases create enough differentiation for an agent to select it appropriately.

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 the description doesn't need to restate safety. It adds value by specifying that the list is scoped to the caller, includes only active subscriptions by default, and returning the exact field set. 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?

Two concise, information-dense sentences. The first states the purpose and return fields; the second gives usage guidance. No redundant words or repetition of schema/annotation details.

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

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

Despite lacking an output schema, the description lists all return fields and clearly explains the tool's scope. With a single optional parameter and clear sibling context (subscribe/unsubscribe), this is complete enough for a read-only list operation. Minor omissions like pagination or sorting are not critical here.

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 single parameter include_inactive is fully described in the schema (100% coverage), including its default behavior ('default false'). The description adds no additional parameter semantics, so the baseline of 3 is appropriate when the schema already handles the 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 uses the specific verb 'List' with a clear resource ('active subscriptions') and names the exact return fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe and unsubscribe, making its function immediately obvious.

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

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

The description explicitly states when to use the tool: 'before adding more' and 'to find an id to cancel.' This provides clear usage context and implicitly differentiates from subscribe/unsubscribe, though it does not explicitly name those 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, so the description carries full responsibility. It discloses rate limiting (5 per identifier per day), the claim_token lifecycle for asynchronous response tracking, that it doesn't count against quota, and that the team reads digests daily. 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 long but every sentence earns its place, covering purpose, usage, exclusions, token flow, rate limits, and quota. It is front-loaded with purpose and avoids redundancy, though a bit dense as a single paragraph; minor formatting improvements could boost 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?

Given there is no output schema and all parameters optional, the description needs to be self-contained. It fully explains the return token, how to later read status, and the asynchronous nature, leaving no critical gaps for an agent to use it correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds value by giving a concrete claim_token usage example ('pwfb_…') and instructing users to describe issues in terms of Pipeworx tools rather than pasting user prompts—helpful guidance beyond the bare field descriptions.

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

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

The description opens with an explicit, specific action ('Tell the Pipeworx team') and enumerates exact subjects (broken, missing, needs to exist). It is clearly distinct from siblings like ask_pipeworx, which handles questions rather than feedback.

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 trigger conditions for each feedback type (wrong/stale data = bug, wish tool existed = feature, etc.) and a clear exclusion: only for tools from this Pipeworx connection, with guidance for tools from other MCP servers. Also gives a heuristic for identifying Pipeworx 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?

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds valuable context: it mentions the data is cached for 5min-1h depending on the window, contains no PII, and has a specific data shape '(pack, tool, count)'. It also notes it is derived from CF analytics-engine, giving the agent confidence about the data source without contradicting any 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 appropriately sized and well-structured: a concise opening sentence, a clear list of use cases, and a final sentence with technical caveats. No word is wasted, and each clause adds information that is not already in the schema or annotations.

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 adequately explains return values ('Returns the top tools, top packs, and total call volume') and data shape ('just (pack, tool, count)'). The tool is simple (one optional parameter), annotations cover safety, and the description covers caching and privacy, so it is complete for an agent to select 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% for the single optional 'window' parameter, and the schema description already explains the enum values and their tradeoffs. The tool description only restates 'over a recent window (24h, 7d, or 30d)' and adds cache timing tied to the window, which is minor. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb ('Returns') and clearly identifies the resource ('top tools, top packs, and total call volume') and scope ('over a recent window'). It distinguishes itself from siblings by emphasizing this is a self-aggregating signal of what other agents are calling on Pipeworx, distinct from discovery or alert 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 'Useful for' section explicitly lists three concrete use cases: discovering hot data sources for current events, confirming canonical tools, and aligning with typical agent needs. However, it does not explicitly mention when not to use it or name alternative tools (e.g., discover_tools), so it falls short of a 5.

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 goes far beyond by explaining the fill check (theoretical_edge_pp_at_book vs realizable_edge_pp), the semantic anchor threshold (≥0.30 Jaccard similarity), and partition filtering (placeholder fraction >20% returns null). This discloses edge-case behavior and limits not visible in structured fields.

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

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

The description is long but densely informative, with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a defined response structure. It is not wasteful; however, it could be tightened slightly (e.g., some repetition of 'event' explanation). Very near-optimal for a complex tool.

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

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

With no output schema, the description fully covers return values: opportunities[], partition_check fields, and fill-check outputs. It also addresses failure modes (skipped_low_similarity, null arb signal) and operational cautions (realizable_edge_pp ≤ 0). This is complete for a tool of this complexity.

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

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

Schema description coverage is 100%, but the description adds rich meaning beyond the schema: it explains each mode's internal logic, gives multiple examples (e.g., 'fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and clarifies that full URLs are accepted. This goes well beyond the baseline 3 for full schema coverage.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates from siblings by detailing its unique mechanism and explicitly references polymarket_fill_risk for custom sizing, distinguishing its scope.

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

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

It provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative tool ('For custom sizing use polymarket_fill_risk') and gives a concrete caution ('do not trade it' when realizable edge ≤ 0).

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 mark it read-only and non-destructive, and the description goes far beyond: it details the response segments (by_segment, fed_candidates, _diagnostics), the 24h-move warning, Kelly caps, filter thresholds, placeholder-slug rules, and caching behavior ('Cached 1h at the KV level'). No contradiction with annotations; this exceeds the transparency bar.

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 structured with ALL-CAPS headers, numbered model families, and clear segmentation, making the dense content navigable. It is verbose (roughly 300 words) but nearly every sentence adds unique detail, and the front-loaded purpose sentence grounds the reader. Minor redundancy (e.g., knob explanations repeated in the description and schema) keeps it from a 5.

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 and 9 parameters, the description fully specifies the response top-level structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, etc.), filtering rationale, and even why Fed bets are excluded. This leaves no major context gaps for an agent to invoke 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?

The input schema already covers 100% of parameters, so the baseline is 3. The description adds extra semantic context by grouping knobs (e.g., 'TRADEABLE-EDGE KNOBS') and explaining subtle behaviors like partition_overround always returning kelly_fraction_half=0 at the parent level, which clarifies why min_kelly doesn't apply to partitions. This gives it a clear edge over the bare 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 opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb, resource, and purpose. It is explicitly positioned as a discovery tool ('what should I bet on today') and outlines distinct model families (model_driven, structural_arbitrage, concentrated_longshot), which clearly differentiates it from sibling tools like polymarket_arbitrage 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?

Gives a clear use case ('agents discover opportunities without paging hundreds of markets') and explains how knobs like min_liquidity/max_spread_pp filter tradeable edges, and how min_partition_leg_kelly works for partitions. However, it does not explicitly say when to choose this over sibling tools (e.g., polymarket_arbitrage) or state negative usage scenarios, so it stops short of full when/when-not 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?

Beyond the read-only/idempotent annotations, the description discloses critical behavioral details: the response structure (tracked, expired, snapshot_dates), the 60-day snapshot TTL limit, data gaps on cache-miss days, and that decay is based on daily closes of edge_pp_net (not intraday). This is rich, non-redundant 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 with clear Args, RESPONSE, and LIMITS sections. Every sentence contributes new information, and the structure aids readability despite the length, avoiding any 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?

With no output schema, the description fully explains the return values (tracked, expired, snapshot_dates) and their semantics, including edge cases like gaps and TTL. This is exceptionally complete for a tool of this complexity, leaving little ambiguity.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value by explaining 'days' as lookback with defaults and max, and 'window' as a snapshot family (24hr | 1wk | 1mo), giving conceptual meaning beyond the schema's type/description.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by emphasizing historical tracking over snapshots, making its unique value explicit.

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 strong use-case framing ('Answers how long...'), and the example about a fresh vs. 3-week-old edge implies when to use this tool. However, it does not explicitly name alternatives or state when not to use it, relying on the sibling list and 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 indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral context beyond annotations: it walks the order-book ladder, returns slippage and fill prices, provides a verdict (clean/degraded/cannot_fill), and warns that partial basket fills convert an arb into an unhedged directional position. This is exactly the kind of behavioral disclosure needed, and it does not contradict 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 a single dense paragraph, but every sentence carries useful information including modes, parameters, outputs, and risk warnings. It is front-loaded with the main purpose. However, it could be better structured with bullet points or section breaks to improve scannability given the length and 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?

For a tool with no output schema, the description provides extensive details on return values: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd, forced_directional_risk. It also covers both modes and the practical context of when to use the tool, making it fully complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds significant meaning beyond schema. It explains size_usd as "max spend on buys, target proceeds on sells" in single-market mode and as "settlement notional S (shares per leg; each share pays $1)" in basket mode. It also clarifies how side defaults work in basket mode based on partition sum. This greatly enriches parameter understanding.

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

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

The description opens with a specific, precise statement: "Realizable-vs-theoretical edge check against live CLOB order-book depth." This clearly names the verb (check), resource (edge against live depth), and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than signal generation.

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?

Usage guidance is explicit and actionable: "USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500." It also clarifies when to use single-market vs basket modes, and explains why (partial fills create unhedged directional risk). This provides clear when-to-use and differentiates from 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 goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by disclosing the matching algorithm (token-overlap, keyword-based), the meaning of null in temporal_alignment, the fee modeling gap ('does not model Kalshi's fee schedule'), and the caveat that compatibility fields can be non-empty even with matched_pairs>0. It also explains skipped/unclassified leg handling. No contradiction with annotations exists.

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

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

The description is long but well-structured with clear label sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, counters). It is front-loaded with the core purpose. Some redundancy exists, such as explaining temporal_alignment null meaning in the prose and again in the code list, but overall each major section serves a distinct informational need.

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 carries the full burden of explaining the response. It covers leg-by-leg prices, spread fields, compatibility codes, temporal alignment, fee caveats, and skipped counters. It even explains edge cases like null alignment and when legs are never paired. This is as complete as an agent needs for correct invocation and interpretation.

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 adds meaningful semantics beyond the schema: it explains that topic maps to a pre-defined event on each venue, that explicit params override the topic-mapped side, and that BOTH modes run the identical matcher. It does not add much per-parameter format detail beyond examples, hence a 4 rather than a 5.

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, unambiguous purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names both venues, the subject (spread), and the scope (same resolving question), which is clear. However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edges, so it stops short of the top score.

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

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

The description gives clear internal usage guidance: it explains TWO MODES ('topic' shortcuts vs explicit ticker/slug), states when to use each, and warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning today. It does not explicitly contrast this tool with sibling alternative tools (e.g., when to use spread vs arbitrage vs edges), so it lacks explicit when-not-to-use-vs-other-tools 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it explains scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior of retrieving vs listing. 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?

Three sentences, each earning its place: function, use cases, and scope/relationship. No filler, front-loaded with the core 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?

For a simple tool with one optional parameter and no output schema, the description fully covers what it does, when to use it, scoping rules, and its relationship to siblings. It hints at return values ('Retrieve a value' / 'list all saved keys'), which is sufficient given the absence of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the parameter semantics by explaining that 'key' refers to a value previously saved via 'remember' and reiterates that omitting it lists all keys. This adds meaning beyond the schema's terse 'omit to list all keys'.

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

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

The description uses a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly distinguishes the two modes: retrieving a value or listing all keys. It also differentiates from siblings by naming 'remember' and 'forget' as the save/delete counterparts.

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 clear context for when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and explicitly names alternatives for related operations: 'Pair with remember to save, forget to delete.' This gives the agent actionable guidance on tool selection.

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

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

The description discloses crucial behavioral nuance beyond the annotations: mark_read:true modifies the read state, a side effect not captured by readOnlyHint=true. It also explains the persistent nature of the feed and the alternate URL for external access. This transparency is especially valuable given the annotations might otherwise mislead an agent into thinking the tool is completely read-only.

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 four sentences, front-loaded with the core purpose ('Pull fired events from your subscription feed'), and each sentence adds distinct value: return format, filtering, mark_read behavior, and polling/alternative access. No fluff or repetition; it is appropriately sized for the tool's simplicity.

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?

In the absence of an output schema, the description helps by mentioning that returned events carry 'source, citation_uri (pipeworx:// when available), and the raw event payload.' It also covers filtering, mark_read semantics, polling suitability, and an external mirror URL. It does not discuss edge cases like pagination or errors, but for a read-oriented tool with good annotations, this is largely sufficient.

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

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

Although the schema already describes all 5 parameters (100% coverage), the description adds practical meaning by giving a concrete type example ('sec_8k'), noting the ISO timestamp format for 'since', and explaining the consequence of mark_read ('so the next call only shows newer ones'). This goes beyond the schema's one-line descriptions, enhancing the agent's understanding of how to use the parameters effectively.

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 the specific verb 'Pull' and 'Returns' with a clear resource: 'fired events from your subscription feed.' It distinguishes itself from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which sounds like changes, not alerts). The mention of 'persisted feed' and the event payload further pins down its 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?

The description gives clear usage context: 'Filter by type (e.g. "sec_8k") and/or since' and 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' It also notes 'Polls work fine' and provides an alternative for scripts/dashboards via a URL, which helps the agent decide when to use the tool. However, it does not explicitly contrast with sibling tools, only implying that this is for reading alerts as opposed to managing subscriptions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), it discloses the multi-source fan-out, fallback chain, USPTO soft-fail due to PatentsView API sunset, and the exact return structure (changes[] grouped by source + total_changes + citation URIs). No contradictions with 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 dense but efficiently organized: query intents, fan-out behavior, parameter format, return format, and alternative tool. It could be slightly trimmed (six query examples are redundant), but every sentence serves a purpose and the structure is easy to scan.

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 multi-source, fallback-capable tool with no output schema, the description covers purpose, parameter formats, source behavior, and return values. It also addresses the one relevant sibling tool. Complete for an agent to select 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 covers 100% of parameters with detailed descriptions and examples. The description reiterates `since` relative shorthand and typical monitoring values, but adds no parameter-specific semantics beyond the schema. It does contextualize why the parameters matter (parallel call, source grouping) but offers no new meaning.

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 multiple natural-language query examples and then states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It explicitly names the fan-out sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling entity_profile by naming it directly.

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

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

Explicitly advises 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also gives clear use-case examples and documents fallback behavior (GDELT→GNews when rate-limited or 5xx), setting expectations for when and how to rely on 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?

The description adds valuable behavioral context beyond annotations: key-value pair scoping, persistent memory for authenticated users vs. 24-hour retention for anonymous sessions. This complements the annotations (readOnlyHint false, idempotentHint true) without contradiction, providing a fuller picture of the tool's 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?

Description is appropriately concise and front-loaded: the first sentence states the primary action, followed by usage guidance, storage characteristics, and companion tool references. Every sentence adds value with no fluff or 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 2-parameter write tool with no output schema, the description covers purpose, when to use, persistence semantics, scoping, and related tools. There is no significant missing context; the annotations handle non-destructiveness and idempotency, completing the picture.

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?

Input schema covers 100% of parameters with descriptions and examples. The description adds minimal parameter meaning beyond restating key-value storage, though it does suggest the kinds of value content (findings, addresses, preferences, notes). Since schema coverage is high, a 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's purpose with a specific verb ('Save data') and identifies what it saves (data for reuse later). Provides concrete examples (resolved ticker, target address, user preference, research subject) and distinguishes it from sibling tools by explicitly naming recall and forget as companions.

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

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

Gives clear context for when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also instructs to pair with recall for retrieval and forget for deletion, effectively guiding usage relative to related tools. However, it doesn't explicitly state when not to use it, leaving alternative storage mechanisms unaddressed.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behaviors: it cascades through several lookup endpoints, degrades gracefully when LEI/FIGI enrichment is unavailable, explicitly reports unresolved identifiers, and returns figi_candidates rather than asserting an ambiguous match. These are exactly the behavioral details an agent needs to interpret results.

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 and dense, but nearly every sentence carries functional guidance for a complex tool with two entity types and multiple cascading lookups. It is front-loaded with the core purpose and usage trigger. The main cost is readability; a structured list or tighter formatting would improve scannability without losing content.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It specifies what identifiers are returned, how ambiguous matches are handled, what happens when enrichment fails, and what fields appear in drug results. An agent has enough context to call the tool correctly and interpret its response.

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 a baseline of 3 applies, but the description adds substantial semantic value. It explains valid formats (ticker, CIK, ISIN, name), gives concrete examples, clarifies that the entity name should be passed alone, and warns about trailing security-class words for bond issues — all 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 states a specific verb+resource: resolve a user-spoken name to canonical/official identifiers, with concrete example phrasings. It clearly distinguishes this from sibling tools like entity_profile and compare_entities by focusing on identifier lookup as the precursor to other tools' input needs.

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 FIRST whenever you have a name but need an ID,' which is a clear trigger condition. It also gives type-specific guidance, explains which inputs are accepted for company vs drug, and warns against passing full noun phrases for bond lookups, helping an agent choose and use it correctly.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context by explaining the internal process (probes each entity with ai_visibility_check, ranks by score) and output structure (ranked list with score, confidence, signal density). It does not discuss rate limits or error handling, but the added process detail 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 three sentences, front-loaded with the primary action, followed by scope and use case. Every sentence contributes information without redundancy. It is concise 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?

The description explains the output format (ranked list with score, confidence, signal density), the use case, and how the tool relates to ai_visibility_check. However, it lacks details on error behavior, rate limits, or how the ranking is computed beyond 'by score'. Given the tool's moderate complexity and absence of an output schema, this is a minor gap.

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 the schema already documents all parameters including the 'first entry treated as subject' behavior. The description does not add much beyond the schema; it restates the models options that are already in the parameter descriptions. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This specific verb+resource+scope distinguishes it from siblings like ai_visibility_check (single entity) 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 explicitly mentions the tool is useful for competitive AI-marketing audits and gives an example query. It implicitly differentiates from ai_visibility_check by focusing on multiple entities, but does not explicitly state when not to use it or name alternative tools for single-entity checks.

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, non-destructive, but the description goes beyond by disclosing graceful degradation on partial failures, the 5-30s first-measurement timeout for bundlephobia, and the sources_failed field. It also notes NPM-only v1 scope. 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 five dense, information-rich sentences, each earning its place: purpose, usage, output fields, ecosystem scope, and failure behavior. It is front-loaded with the main check and avoids redundant repetition of the title or schema.

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 composite tool with multiple data sources, the description fully accounts for complexity: it lists output fields, mentions per-advisory detail and links, specifies ecosystem limits, and explains timeout/partial-failure behavior. With no output schema, the description itself supplies the necessary return-value 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%, so baseline is 3. Both parameters have clear descriptions in the schema (package name with scoped support, version defaulting to latest). The description adds no new parametric meaning beyond what the schema already provides, though it does contextualize the parameters within the composite check.

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: 'Composite "should I add this npm package to my project" check in ONE call' and explicitly names the two fan-out sources (deps.dev and bundlephobia). It clearly distinguishes this tool from siblings (none of which are npm package analysis) and states the ecosystem limitation.

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

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

Explicit usage triggers are given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides a when-not: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing users to alternative handling 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?

Goes beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing the embedding model (BGE-base-en), windowing strategy (500-char overlapping), output features (character offsets, similarity scores), and truncation behavior with flagging. 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?

Every sentence earns its place: purpose, use case, workflow pairing, and technical details are packed efficiently. No redundancy or filler; the description is front-loaded with the core function.

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

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

For a tool with no output schema, the description compensates by explaining what the agent gets back (top-N passages with offsets and scores), the operational constraints (200K cap, truncation flag), and the integration with another tool. This is fully complete for selecting and invoking 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 already covers all parameters with descriptions, so baseline is 3. The description adds meaningful examples for the query parameter and clarifies the 'text' parameter context (already-fetched record, size cap), enriching 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 performs semantic search inside a fetched record (specific verb+resource), and explicitly contrasts with sibling tools by emphasizing it works on text already pulled. It distinguishes itself from broader search tools like box_search or ask_pipeworx by its 'INSIDE a fetched record' scoping and output of passages with offsets.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for a workflow. It also sets expectations about input size cap, making the usage context 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 only indicate read/write/destructive/idempotent hints. The description adds substantial behavioral context: OAuth requirement (anonymous/BYO can't persist), delivery channel specifics (feed always on, email/SMS/webhook), SMS verification and cap, webhook signing secret returned only once, and auto-disable after 10 consecutive failures. This goes well beyond the structured 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 dense paragraph that front-loads the main purpose and then systematically covers types, examples, and delivery channels. While long, every clause adds useful information; no redundant filler. It could be broken into clearer sections, but the structure is logical 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?

For a tool with nested objects and no output schema, the description is remarkably complete. It covers purpose, return value, prerequisites, supported types with examples, all delivery channels, and critical constraints (verification, caps, webhook signature). The agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the always-on feed and how to pull it (via recent_alerts or GET registry.pipeworx.io/alerts.json), plus reinforcing SMS constraints and webhook verification rules. This provides operational detail not explicitly in 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts, which are about managing or reading subscriptions rather than creating one.

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 clear context for when to use the tool (e.g., monitoring live-data event streams) and detailed conditions (requires OAuth account, types available), but doesn't explicitly name alternatives or when-not-to-use cases. This falls short of the 'explicit when/when-not/alternatives' bar but exceeds simple implied usage.

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=true, openWorld=true, idempotent=true, destructive=false. The description adds behavioral context beyond annotations: it returns category-bucketed questions drawn from a live catalog, and explains the output shape. No contradictions. Slight deduction because it doesn't discuss rate limits or side effects, but annotations cover safety.

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 dense paragraph, but every sentence earns its place. It front-loads natural language queries and then explains the output and usage. Slightly long, but appropriate for the tool's complexity and the need to convey onboarding 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 tool's complexity, presence of annotations, and lack of an output schema, the description fully covers return value structure (category-bucketed examples with tool+argument shape), argument behavior (with/without topic), and when to use. 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 has 100% coverage for the single optional `topic` parameter. The description adds meaning by enumerating example topic values ('finance', 'pharma', 'betting') and explicitly stating that omitting `topic` yields a cross-category spread, which goes beyond the schema's simple 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 uses a specific verb ('suggest questions') and clearly states the resource (Pipeworx's capabilities). It distinguishes itself from siblings by positioning as the 'onboarding entry point' and listing what it returns (category-bucketed example questions with exact tool + argument shape). No ambiguity.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also gives guidance on when to pass `topic` vs omit, effectively covering 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?

The description discloses that the row is deactivated rather than deleted, which directly explains the non-destructive behavior beyond the annotations. It also adds the ownership enforcement detail and notes that historical events remain available via 'recent_alerts'. This provides valuable context that the annotations alone do not convey, and there is 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 extremely concise, using only two sentences. The first sentence delivers the core purpose immediately, and the second adds relevant constraints and side effects without any fluff. Every word 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?

For a simple tool with one parameter and no output schema, the description fully covers the necessary context: the action, the ownership constraint, the non-destructive behavior, and the impact on historical events. It is complete for an agent 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?

The schema coverage is 100%, and the parameter 'id' is already well-documented as the subscription id returned by 'subscribe'. The description simply repeats 'by id' without adding additional parameter-level context. Baseline 3 is appropriate because the schema handles the parameter meaning.

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 the action explicitly: 'Cancel a subscription by id.' It clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the operation and the ownership constraint. The scope is precise and 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?

It provides clear context for when to use the tool (cancelling a subscription) and an important constraint (only your own subscriptions). It does not explicitly name alternative tools, but the purpose is self-evident and ownership enforcement is a practical guideline. A slight improvement would be to mention 'list_subscriptions' as the counterpart for viewing active subscriptions, but the guidance is adequate.

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, and non-destructive, and the description adds meaningful behavioral context: the distinction between "could_not_verify" (check did not happen, carries verification_error) and "unsupported" (no source covered), and the reversible routing logic. It also explains the output verdict set and the citation format, which is valuable beyond 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 typical but every sentence contributes: examples, use case, routing logic, output definition, error-handling caveat, and efficiency claim. It is front-loaded with easy-to-grep phrases and avoids fluff, though it could be slightly tightened.

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 defines the full verdict set and provides critical edge-case semantics. It also explains why this tool is efficient (replaces multiple calls). It does omit some minor details like exact citation format and behavior for "inconclusive", but given the complexity and annotations, it is largely 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% with both parameters well-documented. The description does not add new parameter-level meaning beyond the schema; it only reiterates that tolerance overrides wording. Since the schema already handles parameter semantics thoroughly, a 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 opens with concrete example phrasings ("fact check", "verify the claim that…") and immediately identifies the verb+resource: natural-language claim verification against authoritative sources. It also differentiates from siblings by explaining the fast path for company-financial claims versus the grounded pipeline for any other claim, and notes it replaces 4–6 sequential calls.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives usage nuance for the two claim types (SEC EDGAR vs. grounded pipeline) and instructs callers on how to interpret "could_not_verify" vs "unsupported", which is critical for proper use. It doesn't explicitly name alternatives like deep_research, but the scope is clear.

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