Openfoodfacts

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 useful context about auth and cost: 'BYO key — you pay Anthropic directly' and the default free model. It also discloses the return structure, which is valuable since no output schema 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 front-loaded with purpose, then provides key details (default model, cost, return format) and ends with use cases. Every sentence adds value and there is no unnecessary 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 compensates by specifying the exact return: 'per-model {score, confidence, signals, raw_response} + a combined view.' Parameters are fully described in the schema, and the description covers defaults, cost, and usage contexts, making it 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 coverage is 100% with descriptions for all 4 parameters. The description adds extra nuance beyond the schema, such as the default model being free and the implication that _apiKey is only needed for Anthropic. This builds on the schema without redundancy.

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

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

The description clearly states a specific action: 'Probe one or more LLMs for what they know...' and a distinct outcome: 'score visibility (0-100) per model.' This distinguishes it from siblings like ask_pipeworx or deep_research by focusing on AI visibility scoring across LLMs.

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

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

The description provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not mention exclusions or alternatives, but the context is clear enough to infer when to use this tool.

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

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

The description discloses key behaviors beyond annotations: routing among 5,462 tools, filling arguments, returning structured answers with citations, and being a fast default entry point. It does not contradict the readOnly/idempotent annotations. However, it omits potential failure modes or limitations such as what happens when no source matches.

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 long, dense paragraph (~230 words) with repeated examples and parenthetical clarifications, which makes it less concise than ideal. While it is front-loaded with the key purpose, it could be better structured with bullet points or shorter sentences to improve scannability.

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

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

Given the tool's high complexity and absence of an output schema, the description explains the return format (structured answer with pipeworx:// citation URIs) and provides extensive context about when to use it and its alternatives. However, it does not mention edge cases, error handling, or query limitations, leaving small gaps.

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

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

The input schema fully covers the required 'question' parameter and its aliases (q, text, input, query, prompt) with descriptions. The tool description adds no new parameter-level semantics beyond examples; schema coverage is 100%, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: it routes questions to the appropriate one of 5,462 tools across verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It includes concrete examples and explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit guidance on when to use the tool vs alternatives: 'PREFER OVER WEB SEARCH' for factual queries, 'START HERE for most questions' as default, and specific step-up conditions for ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). It also addresses breaking-news use cases.

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

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

Annotations already indicate a read-only, non-destructive, idempotent tool, but the description adds meaningful context: it's a live experimental edge, candidates can be enabled during testing, and there is an explicit fallback clarification that it remains a fully working router. It also provides the current state (no active candidate as of 2026-07-26), which is valuable for the agent's decision-making.

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

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

The description is moderately lengthy but every sentence contributes: it identifies the tool, specifies equality with ask_pipeworx, explains the live testing status, and clarifies the fallback behavior. The parenthetical with tool/argument/response details is somewhat dense but relevant. Overall, it is well-structured and front-loaded with the core identity.

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

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

For a simple single-question tool with full schema and rich annotations, the description covers the essential contextual points: its relation to ask_pipeworx, experimental nature, current behavior, and full functionality. It doesn't detail the response shape, but the mention of 'same response shape' as ask_pipeworx and the sibling tool's existence provide enough context for the agent to infer expected outputs.

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

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

Schema coverage is 100%, with all six parameters being aliases for the single `question` field, each described in the schema. The description adds no extra parameter semantics, but the schema fully documents the aliases and the primary field, meeting the baseline for full 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 clearly identifies this as the beta version of ask_pipeworx, a universal router with the same tools and arguments as the stable version. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental routing candidate. The purpose—providing an experimental but fully functional alternative to ask_pipeworx—is 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 states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it's a live-testing variant and that results are compared against the stable router, making the choice between alternatives clear. It further notes that no candidate is currently active, so behavior matches ask_pipeworx exactly at the moment, guiding the agent to use it just like the stable version.

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

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

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond them by detailing the explicit refusal behavior with refusal_reason enum values, the extra LLM call cost, and the guarantee that only tool-result content is used, adding rich behavioral context without contradicting annotations.

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

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

The description is dense yet well-structured, front-loading the core purpose and then adding necessary details about routing, output shape, refusal reasons, usage scenarios, and cost tradeoff. Every sentence contributes unique value, and there is minimal 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?

With no output schema, the description fully compensates by enumerating the success return fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and the explicit refusal_reason enum values. It also covers edge cases like no_tool_match and data_truncated, making the tool's behavior well understood even without additional structured 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?

Input schema coverage is 100%, with all six parameters documented as aliases for the 'question' field. The description adds no parameter-level detail, but since the schema fully describes the parameters, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' that routes and fetches data, then extracts answers only from the tool result. It explicitly distinguishes itself from the sibling ask_pipeworx by highlighting the grounded extraction behavior, so purpose is specific 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?

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool versus the alternative, with high-stakes scenarios listed as examples.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing safety mechanisms (low-confidence match short-circuits, status codes), resolver contract, parent-event extractor, news fallback behavior, and resolution-rule risk (e.g., refund_50_50 consequences). This is exceptionally transparent and adds context the annotations do not 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 extremely long and dense, which can be overwhelming for an AI agent. However, it uses clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and the opening sentence immediately states the tool's purpose and input format. It is structured but not concise; every sentence carries information, but the sheer volume makes it less accessible.

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 fully compensates by detailing response shapes (result.market, result.analysis, result.evidence), resolver contract fields (market_match_confidence, alternatives, suggestions), parent_event structure, news fallback annotations, and blocking status codes. This makes the tool's complex behavior and return values completely understandable without 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?

The input schema already covers all three parameters with descriptions (market, depth, include_raw), and schema coverage is 100%. The description repeats some of this (e.g., market slug/URL/question text) but does not add significant new information about the parameters' semantics beyond what the schema provides. It neither clarifies depth behavior nor include_raw trade-offs beyond the schema, so 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 a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly states when to use the tool ('Use for...'), and provides detailed fan-out examples across many categories. However, it does not explicitly mention when not to use it or name alternative 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?

The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds no extra behavioral details such as pagination behavior, sorting, or return format. It does not contradict annotations but also provides no value beyond 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 a single short phrase, 'Products by brand,' with zero unnecessary words. It is front-loaded with the core noun 'Products' and immediately states the filtering dimension. The extreme brevity is a positive trait for conciseness, though it sacrifices detail captured in other dimensions.

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 an output schema and annotations, the description has some support. However, it fails to elaborate on pagination or the nature of the returned product list. For a tool with three parameters, this minimal description leaves significant gaps in usage understanding, especially since no alternative guidance is provided.

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

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

Schema description coverage is 0%, so the description must compensate by explaining the parameters. It only hints at 'brand' through the tool name and description, but does not explain 'page' or 'page_size' at all. While page and page_size are conventional, their semantics are not explicitly defined in either the schema or 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 'Products by brand' clearly communicates that this tool returns products filtered by a specific brand, distinguishing it from similar tools like 'category' or 'product'. However, it lacks an explicit verb (such as 'list' or 'get'), making it a noun phrase rather than a full action statement.

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?

There is no guidance on when to use this tool versus alternatives. The sibling tools 'category' and 'product' suggest related functionality, but the description provides no context for selecting 'brand' over them. No exclusions or comparisons are given.

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 show readOnlyHint, idempotentHint, and non-destructive behavior, so the description carries a lower burden. However, it adds zero behavioral context beyond what annotations provide—no mention of result limits, filtering semantics, or whether categories are exact matches. It is consistent with annotations but not additive.

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 short, which avoids redundancy, but it is under-specified. A noun phrase like 'Products by category.' does not provide enough actionable detail for a tool with three parameters and pagination semantics. This is not concise effectiveness; it is minimalistic to the point of being unhelpful.

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 an output schema present, return values need not be explained, but the description still lacks essential usage context. It does not clarify whether this returns a list, supports pagination, or how it differs from product/brand queries. The tool is simple, but the description is too thin for an agent to select and invoke it correctly without additional assumptions.

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

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

Schema description coverage is 0%, so the description must compensate, but it only mentions 'category' implicitly. It does not explain the role of 'page' or 'page_size' (though their names are self-explanatory) nor the required vs optional relationship. The example in the schema provides some context, but the description itself adds minimal 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 'Products by category' clearly identifies the resource (products) and the filtering dimension (category), which distinguishes it from sibling tools like 'product' or 'brand' even without an explicit verb. It is slightly less direct than a verb-led description, but the intent is 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?

There is no guidance on when to use this tool versus alternatives such as 'product', 'brand', or 'search'. The description does not state prerequisites, category matching behavior, or pagination expectations, leaving the agent to infer usage from the name and schema alone.

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?

Even with annotations declaring readOnly/openWorld/idempotent, the description adds substantial behavioral context: which financial metrics are pulled, SEC EDGAR/XBRL source, correct handling of off-calendar fiscal years, sorting by primary metric, and pipeworx:// citation URIs in 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?

Dense, well-structured description front-loaded with trigger phrases. Every clause adds value: entity limits, data sources, fiscal-year handling, sorting behavior, and output format. No filler or repetition.

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

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

For a tool with no output schema, the description fully explains what results look like (paired data + citation URIs), how results are sorted, and which data domains are covered. It also explains the efficiency benefit (replaces many lookups), making it complete for agent selection.

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 100% of parameters with enums and examples. The description adds value by explaining what each type retrieves (10-K metrics vs FAERS/FDA/trial counts) and the expected value formats for companies and drugs.

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 explicit trigger phrases and states the verb+resource: side-by-side comparison of 2–5 companies or drugs in ONE parallel call. It also differentiates from sequential single-pack lookups by noting it replaces 8–15 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?

Provides clear when-to-use guidance: when user asks comparison phrases like 'X vs Y' or 'rank these companies', and explicitly instructs ALWAYS PREFER over sequential single-pack lookups. It also specifies the two entity types and their data sources.

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 a safe, idempotent read operation (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds no behavioral context beyond that, such as pagination behavior, data scoping, or limitations.

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 short, but it is under-specified rather than efficiently concise. It reads as a title or label, not a functional tool description, and fails to earn its place by conveying necessary information.

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

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

Despite having an output schema, the description leaves the tool's overall behavior, list semantics, and usage context unclear. With pagination parameters present, a one-line phrase is inadequate for a complete understanding.

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

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

Schema description coverage is 0%, and the description does not compensate. It merely repeats 'country' from the schema and leaves 'page' and 'page_size' completely unexplained. The description adds no meaning beyond the parameter names.

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 'Products from a country.' is a noun phrase without an explicit verb, so the operation (list, search, or get) is ambiguous. It identifies the resource (products) and a filter (country) but does not distinguish it from sibling tools like 'product' or 'category'.

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 no guidance on when to use this tool vs alternatives. There is no mention of use cases, prerequisites, or relationships to sibling tools such as 'brand', 'category', or 'search'.

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

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

Description discloses account requirements, free vs paid plan implications, decomposition strategy, gap[] handling (never invents), contradiction detection, citation URI validity, semantic excerpting, and latency expectations. This goes far beyond the readOnly/openWorld/idempotent annotations, providing actionable behavioral context without contradiction.

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

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

The description is long but every sentence carries critical information (prerequisites, alternatives, mechanics, output shape, latency). It is front-loaded with the account requirement and key alternatives, though a more compact structure would improve scannability.

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

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

Given the tool's complexity, absence of output schema, and advanced behaviors, the description fully covers expected inputs, outputs, failure modes (gaps), performance expectations, and integration with citations. No significant context 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 description significantly enriches the parameter schema: it explains the practical effect of depth values ('standard' adds gap recovery and contradictions scan, 'thorough' is paid with iterative leads chasing) and clarifies that question accepts broad/multi-part queries. Since schema coverage is 100%, this extra context raises the value.

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

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

The description clearly identifies the tool as grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to 5,462 tools in parallel. It distinguishes itself from ask_pipeworx and open-web search, making its scope 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?

Explicit guidance is given for when to use deep_research (broad/multi-part structured data questions) and when to prefer alternatives (single lookup, breaking/current news, not signed in). It names specific alternative tools (ask_pipeworx) and even covers account tier limitations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description is consistent, describing a read/discovery operation. It adds context beyond annotations by specifying the return payload: 'names, descriptions, and full input schemas (with curated examples)' and guarantees 'no second schema lookup needed.' This is valuable behavioral detail about output composition.

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

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

The description is moderately sized but not excessive, with the core purpose front-loaded in the first sentence. Each sentence adds value: the domain list illustrates scope, the return-format sentence explains output, and the 'Call this FIRST' sentence provides tactical usage. Slightly long due to a 14-item domain list, but not wasteful.

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

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

With no output schema, the description effectively covers the return format and indicates the response is call-ready. Annotations cover safety hints. The tool is not complex (one semantic parameter with aliases, plus an optional limit). The description fully prepares an agent to invoke it appropriately.

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 each parameter (including aliases) explicitly described. The description only adds that the input is a natural language task description, which is already implied by the schema examples. Thus the description adds little beyond the schema, but the schema itself is thorough, so 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 uses the specific verb 'Find' with resource 'tools' and clarifies it discovers tools by describing data/task. It distinguishes from sibling tools by positioning itself as a meta-search tool: 'Call this FIRST when you have many tools available and want to see the option set.' This clearly separates it from data search tools.

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

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

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies an alternative is calling a known tool directly, but doesn't name specific alternative tools or when-not scenarios, so it misses the top tier.

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 and idempotent annotation hints, the description discloses the fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF, and the GDELT→GNews fallback. It details the exact return fields (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents, news, LEI) and notes the patent API sunset and soft-fail. This is rich behavioral context that annotations alone do not 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 information-dense, using examples, a clear main statement, and semicolon-separated return details. It is front-loaded with user query examples then the core action. While somewhat verbose, every sentence contributes functional guidance, and the structure (examples → function → sources → returns → input constraints) is logical and scannable.

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

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

The tool has no output schema, so the description must compensate. It does so thoroughly by enumerating all return components (filings, fundamentals, patents, news, LEI), explaining the parallel-call architecture, and noting fallback/soft-fail states. It also clarifies input constraints and references resolve_entity for edge cases. This is sufficient for an agent to invoke the tool correctly without further 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 schema descriptions already fully document both parameters (type enum 'company' and value as ticker or zero-padded CIK, with names not supported). The description repeats these examples ('AAPL', '0000320193') and the 'names not supported' caveat but does not add any new parameter-level syntax or format information beyond what the schema provides. With 100% schema coverage, the baseline is 3 and the description adds marginal value.

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

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

The description states the tool's primary purpose clearly: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example phrasings and enumerates the exact data sources and return fields, making the tool's function unambiguous. It also distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.'

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

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

The description provides explicit usage guidance: prefer this tool over chaining multiple single-purpose lookups for holistic company research, do not pass names (use resolve_entity first), and accept either ticker or zero-padded CIK. It also discloses the patents API sunset and soft-fail behavior, setting expectations for when results may be incomplete.

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 signal destructive behavior (destructiveHint=true). The description adds value by explaining why deletion might be appropriate (clearing sensitive data, stale context) and confirms irreversibility implicitly. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the action, and avoids unnecessary words. Every sentence contributes to understanding purpose and usage.

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 no output schema and strong annotations, the description covers purpose, usage context, and relationship to siblings. No critical information 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 input schema covers the only parameter 'key' with a clear description ('Memory key to delete'), achieving 100% schema coverage. The description adds little beyond 'by key', so the baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It distinguishes itself from sibling tools like remember and recall by focusing on deletion.

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

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

The description provides explicit use cases (stale context, task done, sensitive data) and references sibling tools (remember and recall), but does not explicitly state when not to use the tool. This is slightly less than full 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds process-level transparency (fetches page, extracts title/description/key links, emits markdown) and clarifies the output format (a text blob for site-root). This goes 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 compact, with a clear main sentence, a process summary, and a bullet-like list of use cases. Every clause adds value, no fluff or redundancy. It front-loads the core purpose and then efficiently elaborates.

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 two parameters and no output schema, the description is remarkably complete. It explains what the tool does, how it works, what output to expect (standard llms.txt markdown), and common scenarios. No critical gaps remain.

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

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

Schema coverage is 100% for both parameters (url and max_links), so the schema fully documents them. The description does not add extra meaning about the parameters beyond what the schema already provides; it only mentions 'key links' generically. 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 generates a production-ready llms.txt file for any URL, with a specific verb+resource (generate + llms.txt). It explains the process (fetches page, extracts metadata, emits standard markdown) and even lists concrete use cases, making it easy to distinguish from sibling tools.

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

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

The description provides clear context for when to use the tool via 'Useful for:' scenarios (indexing client sites, drafting own llms.txt, auditing competitors). It does not explicitly name alternatives or exclusion criteria, but the use-case framing gives strong situational 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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful context by specifying return fields ('id, type, params, created_at, last_fired_at, fire_count') and the 'active' filter scope. No contradictions or hidden side effects.

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

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

Two concise sentences. The first sentence front-loads the core action and resource; the second explains the returns and usage guidance. No wasted words.

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

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

The tool is simple with one optional parameter and no output schema. The description sufficiently explains the return format and provides usage context. It does not explicitly mention the default filtering (active only) or the include_inactive parameter, but the schema covers this, so the description is adequate for the tool's complexity.

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

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

Schema description coverage is 100%, with only one optional parameter (include_inactive) fully described in the schema. The tool description does not mention this parameter but provides no additional semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states 'List the caller's active subscriptions', which uses a specific verb ('List') and resource ('active subscriptions'), clearly distinguishing it from sibling tools like subscribe and unsubscribe. It also lists the returned fields, reinforcing 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 concrete usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations are all false and provide no protective hints, so the description carries full responsibility. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and operational expectations ('The team reads digests daily and signal directly affects roadmap'). This goes well beyond what annotations offer.

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

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

The description is front-loaded with the core purpose in the first sentence, then flows logically through use cases, exclusions, content guidance, and operational constraints. Every sentence contributes unique information; there is no redundancy or filler despite the length.

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

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

The description covers what, when, how, limitations, and outcomes for a no-output-schema feedback tool. The only minor gap is not describing the return value/confirmation after submission, which is not critical for a feedback tool. All parameters and scope boundaries are thoroughly explained.

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 a meaningful content directive for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which refines the schema's generic 'Be specific.' It doesn't add structural details for the context object, so a modest 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' a specific verb+resource that precisely defines the tool's role. It clearly distinguishes this from all sibling tools (which are data/query tools) by being the only feedback-submission mechanism in the catalog.

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 triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion and alternative: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond this: data source (CF analytics-engine), no PII, and caching behavior (5min-1h depending on window). This gives the agent a fuller picture of what to expect.

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 and front-loaded with the core definition. The 'useful for' list adds value but could be considered slightly verbose. Still, every sentence contributes meaning and the structure is logical.

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

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

This is a simple read-only tool with one optional parameter. The description covers the return content, the use cases, the aggregation source, privacy (no PII), and caching. There is no output schema, but the text sufficiently describes the result shape. Complete for the tool's complexity.

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

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

The input schema has full coverage for the single 'window' parameter, including enum values and explanation of shorter vs longer windows. The description mentions the window options but adds no new semantic information beyond what the schema already provides. Baseline 3 per the rubric.

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

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

The description clearly states what the tool does: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'returns' and specific resources (tools, packs, call volume) distinguish it from sibling tools like search or discover_tools.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming a canonical tool, and seeing alignment with agent needs. It does not explicitly say when NOT to use it or name alternative tools, but the context is clear enough for an agent to decide.

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 establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds substantial behavioral context beyond that: Jaccard similarity threshold, partition placeholder filtering, fill check against live CLOB depth, and response structure. Nothing contradicts the annotations, and the extra detail (e.g., 'deviations >3pp emit a BUY/SELL EVERY LEG signal') helps the agent anticipate side effects.

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

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

The description is long but well-structured: it front-loads the main purpose, then breaks down modes, semantic anchor, filters, response format, and fill check. Every sentence is informative, though the length is at the upper bound for an MCP description. It could be tightened, but the organization prevents it from feeling bloated.

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 values and edge cases. It does so comprehensively: opportunities[] fields, partition_check nested object, skipped_low_similarity count, placeholder fraction behavior, and fill check results. For a complex arbitrage tool, this is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the schema already describes both event and topic parameters. However, the description adds meaning beyond the schema: it provides concrete slug examples ('fed-decision-may-2026'), explains the mode semantics and their differing behaviors, and clarifies how the parameter drives the analysis. This is valuable enrichment, not mere repetition.

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+mechanism: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event and topic) and references sibling tools like polymarket_edges and polymarket_fill_risk, so the agent knows exactly what this tool uniquely does.

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

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

The description provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative for custom sizing ('For custom sizing use polymarket_fill_risk') and explains when not to trade (realizable_edge_pp <= 0), giving clear usage boundaries.

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

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

The description goes far beyond the annotations, detailing caching ('Cached 1h at the KV level keyed on all knobs'), edge netting ('edge_pp_net (after slippage)'), Kelly caps ('capped at 0.25'), diagnostics ('_diagnostics...so callers can see WHY a segment is empty'), and the 24h-move warning. 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 well-structured with CAPS section labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and parenthetical details. It front-loads the purpose before diving into internals. Every sentence adds value, though length may be slightly heavy.

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

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

Despite no output schema, the description preemptively answers likely questions: response structure (by_segment, fed_candidates, _diagnostics), why Fed bets are excluded, and knob effects. It fully covers a complex tool with 9 parameters and three model families.

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

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

Schema coverage is 100%, but the description adds meaningful interaction context: 'TRADEABLE-EDGE KNOBS' explains how min_liquidity/max_spread_pp drop opportunities, and 'min_kelly never filters them' clarifies partition arb behavior. This exceeds simple schema descriptions.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This uses a specific verb and resource, and the 'what should I bet on today' framing distinguishes it from sibling tools like polymarket_arbitrage.

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

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

It explicitly mentions the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' However, it does not name alternative tools or provide exclusion criteria, though the context is clear.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds significant behavioral detail: history depth is bounded by the 60-day snapshot TTL, snapshots are written on cache-misses so gaps mean no scan occurred, and decay numbers come from daily closes of edge_pp_net, not intraday. These are non-obvious operational traits that help the agent set expectations.

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 structured: purpose sentence, then Args, RESPONSE, and LIMITS sections. Every sentence adds value, and the formatting with brackets and field names makes the response format easy to parse. No wasted words.

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

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

Given there is no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field names and semantics. It also covers edge cases like snapshot gaps, expiration reasons, and the meaning of lifespan_days. This is complete for an agent to invoke and interpret results effectively.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description repeats defaults (days=14, window='1wk') and adds the term 'snapshot family' for window, but this is marginal over the schema. No extra syntax or format details are provided, so the 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on time-series decay rather than current levels or arbitrage opportunities.

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 strong context for when to use it: analyzing whether a wide edge is fresh or aged, with the insight that 'a fresh wide edge and a 3-week-old wide edge are different trades'. It does not explicitly name alternative tools to avoid, but the purpose is clear enough for an agent to select it over related siblings.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses critical behavioral traits: it 'walks the ladder', returns a verdict, and highlights risks like partial basket fills converting an arb into an unhedged directional position. It warns about the dominant loss mode, adding significant transparency 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 long but densely packed; every clause serves a purpose. It is structured with CAPS emphasis for key modes and a clear flow from single-market to basket to usage guidance. Slight wordiness (e.g., 'theoretical overround on thin books is not capturable') but overall efficient for the complexity.

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

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

For a tool with two modes, no output schema, and rich return data, the description is exhaustive: it lists all return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs, etc. for basket). It also explains the interpretation of results and risks, so the context is complete.

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

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

Schema coverage is 100%, but the description adds substantial meaning: 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 `side` defaults and the `market` vs `event` distinction, enriching the schema definitions.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market vs basket modes and explicitly ties itself to sibling tools polymarket_arbitrage and polymarket_edges, making its unique purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the single-market and basket modes, including defaults and when to choose each, which serves as clear usage direction.

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?

Even though annotations already declare read-only, open-world, and idempotent behavior, the description adds substantial behavioral context: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the explicit warning that aligned:false makes spreads meaningless. This goes far beyond the annotations and reveals critical edge-case behavior.

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

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

The description is structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and is front-loaded with the core purpose. It is longer than average, but each section conveys essential caveats and response details. The SAFETY FIELDS section is a bit verbose, preventing a perfect conciseness score.

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 the response. It describes leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and counters, along with examples and edge cases. For a tool with 3 optional parameters, this is exceptionally 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?

The input schema covers all 3 parameters with descriptions and examples, so baseline is 3. The description adds value by framing the two operational modes (topic vs explicit) and explaining how kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. This supplementary explanation of parameter interactions justifies a score above baseline.

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

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

The description opens with a clear specific statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this tool from siblings like polymarket_arbitrage by explicitly focusing on Kalshi-Polymarket cross-venue comparison. The response section further clarifies it computes spreads between matched outcomes across venues, making the purpose unmistakable.

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

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

The description explains two usage modes (topic shortcuts vs explicit ticker/slug) and when each is appropriate. It also warns that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable,' guiding agents to interpret results cautiously. However, it does not explicitly name alternative tools or state when to prefer 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?

The description adds no behavioral details beyond the existing annotations, which already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. It does not mention what happens on invalid barcodes, data source, or return behavior, leaving the agent without additional 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 extremely brief (four words), which avoids verbosity but borders on under-specification. It is a fragment rather than a complete instruction, though it conveys the core idea efficiently.

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

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

Given the tool's simplicity (one parameter, rich annotations, and an output schema), the description is minimally adequate. However, it fails to provide usage context or edge-case behavior, leaving the agent to infer acceptance criteria from schema examples and the tool's title.

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 has 0% description coverage for the barcode parameter, and the description merely repeats the parameter name in 'by barcode' without elaborating on format, validation, or acceptable values. The examples in the schema are not part of the description, so no extra semantic information is provided.

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 identifies the resource (product) and the input (barcode) but lacks an explicit verb like 'get' or 'lookup'. It reads as a noun phrase rather than a full action statement, making the core purpose inferable but not explicitly stated.

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?

No guidance is provided about when to use this tool or how it differs from sibling tools such as 'brand', 'category', or 'entity_profile'. The description gives no context for selection among alternatives.

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

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

The description adds behavioral context beyond the annotations, notably scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the listing behavior when key is omitted. It also implies the data is persistent and tied to a specific environment. This goes beyond the read-only/idempotent hints, though it doesn't describe edge cases like missing keys.

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 function, followed by usage context and pairing guidance. No wasted words; every sentence contributes distinct information (function, usage, scoping+alternatives). It is concise yet complete.

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

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

For a simple single-parameter tool with rich annotations and a clear schema, the description covers all major aspects: read/list modes, examples, scoping, and related tools. It could mention return behavior on missing keys, but that is a minor gap given the tool's simplicity and the presence of annotations.

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

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

The schema already describes the 'key' parameter well (100% coverage), but the description enriches it with illustrative examples ('user's target ticker, an address, prior research notes') and clarifies the omission behavior ('omit the key argument'). This adds practical meaning beyond the bare schema definition.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes two modes and explicitly references the sibling tool 'remember', making it easy to tell apart from other tools. The examples ('user's target ticker, an address, prior research notes') further anchor 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 provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the complementary tools in the workflow: 'Pair with remember to save, forget to delete.' This gives explicit when-to-use and alternative guidance, effectively differentiating from related operations.

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 readOnlyHint, the description discloses the return payload (source, citation_uri, raw event payload) and the mark_read side effect, which is essential for understanding that the tool can change read state. It also notes the persisted feed and resulting behavior on subsequent calls, adding context beyond annotations.

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

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

The description is four sentences, front-loaded with the verb, and each sentence adds specific value: return shape, filtering, mark_read behavior, and polling/HTTP alternative. There is no filler or redundant repetition.

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

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

With five parameters and no output schema, the description covers the return shape, filtering options, and the stateful mark_read behavior, giving enough operational context. It even mentions an HTTP mirror for external integration, rounding out the tool's 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% with descriptions for every parameter, so the baseline is 3. The description enriches this by explaining how to filter by type and since, and the effect of mark_read, going beyond the schema's one-liners without redundancy.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly identifying the action and resource. It further specifies that it returns alerts written by the evaluator to a persisted feed, distinguishing it from generic read tools and sibling tools like recent_changes.

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 states 'Polls work fine,' indicating suitable polling scenarios, and also points to an alternate HTTP endpoint for scripts, offering an alternative. However, it does not explicitly contrast with sibling tools or state when not to use, leaving exclusions implicit.

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

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

Discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), fallback logic (GDELT preferred, GNews on rate-limit/5xx), and USPTO API sunset soft-fail. It also explains the return structure (changes[] group by source, total_changes count, citation URIs), far exceeding the annotations' readOnly/openWorld/idempotent hints.

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

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

Despite its length, every sentence delivers actionable information: example queries, source behavior, fallback rules, parameter formats, and return value. It is front-loaded with user-intent examples and avoids filler.

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

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

With no output schema, the description fully explains the return format and source behavior. It also notes limitations (USPTO soft-fail), parameter nuances, and directs to an alternative tool for static profiles, making it highly complete for a complex tool.

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

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

The input schema already provides 100% coverage of the 3 parameters with descriptive text (e.g., 'since' meaning window start, type enum, value examples). The description adds example shorthand and source-specific usage but does not meaningfully extend parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly defines the tool as a change feed for a company with explicit example queries ('What's new with X'). It names the verb (get changes) and resource (company), and distinguishes itself from sibling entity_profile via the 'Use entity_profile instead' clause.

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 when-to-use guidance through natural language examples and explicitly names an alternative ('Use entity_profile instead when you want the static profile'). It also states the tool makes 'ONE parallel call', implying efficiency for recent-changes queries.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), it discloses scoping ('scoped by your identifier') and persistence details (authenticated users get persistent memory; anonymous sessions retain for 24 hours). 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, front-loaded with purpose, then usage guidance and behavioral details. Every sentence earns its place with no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema, it covers purpose, usage examples, persistence behavior, scoping, and related tools. It fully prepares the 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?

Schema coverage is 100% with descriptive parameter names and examples. The description adds no parameter-specific information beyond the generic key-value pair concept, so the baseline 3 applies.

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

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

The description states 'Save data the agent will need to reuse later' — a specific verb and resource — and clarifies scope ('across this conversation or across sessions'). It distinguishes from siblings by positioning it alongside recall and forget, clearly identifying 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?

Explicitly says 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference, research subject). It also names companion tools (recall, forget), providing clear alternatives and context for when to use each.

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 a safe, read-only, idempotent operation, but the description adds substantial behavioral context: it explains that each call cascades through several lookup endpoints, that input is auto-disambiguated, and it specifies the exact output fields and citation URIs for each entity type. This goes well beyond the annotations and helps the agent predict behavior.

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

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

The description is dense but well-structured. It opens with user intents, then gives a direct command, followed by detailed support for each type. Every sentence contributes new information, and the length is appropriate for the tool's complexity. No unnecessary repetition or filler.

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

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

Given the tool's two distinct entity types, the description covers all necessary context: what each type returns, accepted input formats, and the internal multi-endpoint behavior. It also mentions citation URIs for downstream use. Without an output schema, the description fully explains the output structure, making it complete for an agent to invoke and understand responses.

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?

Though the schema already covers both parameters with enum and descriptions, the description enriches them significantly. For 'value', it clarifies acceptable formats per type (e.g., ticker, CIK, or company name for 'company'; brand or generic name for 'drug') and the auto-disambiguation behavior. This adds meaning beyond the schema's basic type restrictions.

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's purpose: resolving user-spoken names to canonical identifiers (ticker, CIK, RxCUI). It uses strong verbs like 'resolve' and 'look up', and differentiates from siblings by noting that other tools require these identifiers as input. The supported types and return values are explicitly stated.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This establishes clear context for when to invoke the tool. It also implies when not to use it (when you already have the ID) and highlights that it replaces multiple manual lookups, making it the preferred entry point for entity identification.

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, which covers the safety profile. The description adds meaningful behavior: it probes each entity, ranks by score, and returns a ranked list with score, confidence, and signal density. It doesn't mention potential caveats like API key requirements for certain models, but that is covered in the schema. No contradictions with annotations.

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

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

The description is two sentences long, front-loaded with the primary purpose, and each clause adds value: the operation, the method, the use case, and the return format. It is efficiently written without redundancy or filler.

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

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

The tool has 4 parameters (1 required), full schema coverage, rich annotations, and no output schema. The description covers the return format ('ranked list with score, confidence, signal density per entity') and the multi-entity comparison context. It is complete enough for an agent to invoke correctly, though a note about model-specific requirements could strengthen it further.

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 all parameters are documented. The description mentions 'your brand + N competitors', which slightly reinforces the 'entities' schema description ('First entry treated as the subject'), but it adds no new parameter-specific information beyond what the schema already provides. Per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting and the description adds marginal value.

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

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

The description opens with a specific verb+resource+scope: 'Compare AI visibility across multiple entities side-by-side.' It clearly names the underlying mechanism ('Probes each entity ... with ai_visibility_check') and the outcome (ranks by score, surfaces most/least recognized). This distinguishes it from the sibling tool ai_visibility_check, which handles single entities.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question, making the intended context clear. It implies this is the multi-entity version of ai_visibility_check, but it does not explicitly state when not to use it or name alternatives beyond the underlying probe reference. Since the 'when' is clear but 'when-not' is implied rather than stated, it earns 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?

The description adds significant behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. It also details the output structure. This goes well beyond the readOnlyHint and idempotentHint already provided.

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 is front-loaded with the core purpose, followed by use cases, output, ecosystem scope, and failure behavior. Slightly long, but justified for a composite tool with many details. Could be more scannable but not 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?

The tool has no output schema, so the description compensates by listing the summary block fields, per-advisory detail, links, and alternative versions. It covers ecosystem limitations, latency, and partial failures. Given the tool's complexity, this is fully complete.

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

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

Schema coverage is 100% (both package and version have descriptions). The description does not add additional parameter-specific semantics beyond what the schema already states (e.g., version defaults to latest). 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's purpose: 'Composite should I add this npm package to my project check in ONE call'. It names specific data sources (deps.dev, bundlephobia) and what it checks (license, advisories, bundle size, tree-shaking). This distinguishes it from sibling tools like scan_competitor_ai_presence and search.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description carries a lower burden. However, it adds no behavioral detail about pagination, default sorting, result shape, or scope of the full-text index, leaving significant gaps for a search 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 concise but drastically under-specified. Two words can hardly be considered appropriately sized for a tool with five parameters and a broad search operation. It is closer to a label than a description.

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 an output schema present, return values need no explanation, but the description lacks essential context: what is being searched, any filters beyond the listed parameters, default behavior for paging and sorting, or when to prefer this over search_within or other search-like tools. The tool is not adequately contextualized.

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 only 40%, and only 'fields' and 'sort_by' have descriptions. The tool description, 'Full-text search,' adds no parameter meaning, failing to compensate for undocumented parameters like 'query', 'page', and 'page_size'.

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

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

The description states 'Full-text search,' identifying the verb (search) and a general search mode (full-text), but does not specify the resource or corpus being searched. It does not distinguish from sibling tools like search_within, which implies a similar but scoped search.

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

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

No guidance on when to use this tool versus alternatives. Siblings like search_within and recent_changes suggest different search contexts, but the description provides no indication of when 'search' is the appropriate choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds rich behavioral details: BGE-base-en embeddings, 500-char overlapping windows, a 200K char cap with truncation flagged, and offsets for verbatim quote verification. This goes 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 four sentences, front-loaded with purpose and usage. Each sentence adds value: purpose, when-to-use, pairing with a sibling tool, and technical constraints. No filler, though it is slightly dense.

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 returns: 'top-N passages with character offsets and similarity scores.' It also covers the 200K character cap, truncation flagging, and integration with ask_pipeworx_grounded, making it complete for a search tool.

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

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

Schema description coverage is 100% for all three parameters. The description reiterates that 'text' is 'already pulled' and 'query' is a natural-language query, and gives example queries, but does not significantly deepen semantic understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools like 'search' by emphasizing 'text you already pulled' and 'fetched record.' The output is also specified: 'top-N passages with character offsets and similarity scores.'

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also gives a complementary workflow with 'ask_pipeworx_grounded,' which helps the agent decide between 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?

Beyond the annotations (readOnly=false, idempotent=true, etc.), the description discloses important behaviors: it returns a new subscription id, requires phone verification for SMS with a 10/day cap, explains webhook HMAC signing and secret returned once, and notes auto-disable after 10 consecutive failing runs. 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 long but heavily front-loaded with the core purpose. It uses colons and examples to structure the types and delivery channels. Every sentence carries essential information (verification, caps, webhook details), earning its place, though the density could be slightly reduced.

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 still explains it 'Returns the new subscription id.' It covers all subscription types, delivery channels, authentication requirements, phone verification, rate caps, and webhook behavior. It is sufficiently 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 already has 100% coverage with descriptions for all parameters. The tool description adds extra meaning by explaining real-world examples (e.g., items:["5.02"] = officer change for sec_8k) and cross-venue mispricings for polymarket_edge. This enriches the semantics beyond the schema's property 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 'Create a proactive monitoring subscription to a live-data event stream,' using a specific verb and resource. It enumerates supported subscription types (sec_8k, polymarket_edge, fred_series, etc.) and delivery channels, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

The description provides clear context for when to use the tool: when you need to monitor live events (e.g., SEC filings, market edges). It includes prerequisites (requires a Pipeworx OAuth account; anonymous/BYO cannot persist) and mentions that feed alerts can be pulled via recent_alerts, which gives an implicit alternative for reading. However, it does not explicitly name alternatives like list_subscriptions or unsubscribe.

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

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

Annotations already cover safety traits (readOnly, openWorld, idempotent, non-destructive). The description adds valuable behavioral context: it returns a live catalog-derived set of examples, supports optional topic filtering, and includes tool+argument shapes. This complements rather than contradicts 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 front-loaded with natural user phrasing, then delivers compact, high-signal detail. Each sentence serves a purpose: what it returns, how to call it, and when to use it. No redundancy or filler.

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

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

For a tool with no required parameters and no output schema, this description fully covers invocation, return content, optional filtering, and use case. It even lists the meta-tools one can learn about, making it self-contained for an onboarding 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 documents topic with 100% coverage, so baseline is 3. The description adds useful semantics by explaining the no-argument 'full spread' behavior and providing example values like 'betting', 'finance', and 'pharma', which clarifies intent beyond the schema enum.

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

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

The description uses a specific verb-resource pairing ('onboarding entry point'), states it returns category-bucketed example questions, and clarifies it maps each question to the exact tool and argument shape. This clearly distinguishes it from siblings like ask_pipeworx and discover_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?

Explicitly instructs to 'Use this FIRST' when not knowing what Pipeworx can do, and mentions learning to call meta-tools. However, it does not name alternative tools to use instead, so it stops short of full exclusion 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?

The description goes beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. This adds meaningful behavioral insight not present in the annotations alone, and it aligns with destructiveHint=false.

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

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

Two concise sentences, with the primary purpose front-loaded. Every phrase earns its place, covering purpose, ownership, and deactivation behavior without redundancy.

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

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

Despite lacking an output schema, the description covers all essential aspects for a single-parameter mutation: what it does, ownership enforcement, and persistence semantics. Given the tool's simplicity and good annotations, it is sufficiently complete.

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

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

Input schema already provides 100% coverage, describing 'id' as 'Subscription id (uuid) returned by subscribe.' The description does not add extra parameter meaning or syntax details, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource, and the ownership detail distinguishes it from subscribe/list_subscriptions. It is unambiguous and actionable.

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: you can only cancel your own subscriptions, implying a constraint on when it is valid to use. However, it does not explicitly mention alternatives (e.g., use list_subscriptions to find an id) or contrast with subscribe, so it falls short of the highest bar.

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, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral detail: it returns a specific set of verdicts (confirmed / approximately_correct / refuted / inconclusive / unsupported), includes grounded or structured actual values with pipeworx:// citations, explains the exact percent-delta math for financial claims, and describes the fall-through to live sources. It also mentions the tolerance cap and the ability to override tolerance for hallucination detection. This goes well 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 dense but well-structured: it front-loads with trigger phrases, states the primary use case, then explains routing, return value, and why it replaces multiple calls. Every sentence contributes unique information—no filler or repetition of annotations. The length is justified by the tool's complexity.

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

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

This is a complex tool with dual pipeline routing and a multi-value verdict result, and there is no output schema. The description compensates by enumerating the exact verdicts, the evidence returned (actual value + pipeworx:// citation), and the reasoning. It also covers the tolerance behavior and fall-through logic. Without an output schema, this is a complete and self-contained description.

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

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

Schema coverage is 100%: both 'claim' and 'tolerance_pct' have thorough descriptions in the input schema, including examples and constraints (0.5–50, defaults, usage for hallucination detection). The tool description adds only a few examples of claims and mentions 'exact percent-delta math' but does not meaningfully extend parameter understanding beyond the schema. Baseline 3 is appropriate when schema covers parameters well.

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 natural-language trigger phrases ('Is it true that…' / 'fact check') and clearly states the verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by describing the dual-path routing (SEC EDGAR + XBRL for company-financial claims, grounded pipeline otherwise) and by noting it consolidates what would otherwise require 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?

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs. other claims, providing clear context. However, it does not explicitly name alternative tools or state when NOT to use it (e.g., for open-ended research), so it lacks explicit exclusions/alternatives.

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