Mlb Stats

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds critical behavioral details: default model is free, Anthropic requires a user-provided API key and direct billing, and the return structure includes per-model details. 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 focused sentences plus a return-structure bullet. Every sentence adds value: first sentence explains core function, second covers model options and output. No unnecessary words.

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

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

Despite having no output schema, the description fully specifies return values (per-model {score, confidence, signals, raw_response} + combined view). All 4 parameters are covered with role and examples. The tool complexity is moderate and adequately addressed.

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

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

Schema coverage is 100%, and the description enhances each parameter with concrete examples and clarifications (e.g., entity: 'Pipeworx', context: 'Boston restaurant'). It explains the interaction between _apiKey and models, adding value beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and scores visibility, using specific verbs ('probe', 'score') and outputs (0-100). It distinguishes from sibling tools by focusing on AI visibility auditing rather than generic Q&A or 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 usage contexts (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use different models (free default vs. Anthropic with BYO key). However, it does not explicitly state when not to use this tool versus siblings like 'deep_research' or 'ask_pipeworx', slightly limiting guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond that: it fills arguments automatically, returns citations, works on every tier, and is a single fast call. This enriches the safety profile 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 long but dense, front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Each sentence serves a purpose: routing details, alternatives, examples, and tier behavior. It is slightly verbose but well-structured and not repetitive.

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 (routing across 5,529 tools) and the absence of an output schema, the description adequately explains the output format ('structured answer with stable pipeworx:// citation URIs'). It also covers expected use cases, alternatives, and examples, making it complete for an agent selecting the tool.

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

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

Schema description coverage is 100% – the only required parameter 'question' is fully described along with aliases. The tool description provides no additional parameter-specific details, but the schema already handles the heavy lifting. Baseline 3 applies, as no extra semantic value is needed.

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

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

The description clearly states the tool's purpose: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, thus providing a specific verb+resource with clear scope.

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

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

The description explicitly opens with 'PREFER OVER WEB SEARCH' and includes 'START HERE for most questions — this is the default entry point.' It gives clear when-to-use guidance and step-up alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This fully covers usage context and exclusions.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description reveals that candidate routing improvements are 'enabled live whenever one is under test' and that 'No candidate is active right now,' so it currently matches ask_pipeworx. It also clarifies that it 'Falls back to nothing' and is 'a full working router,' providing essential experimental 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 three sentences, each serving a purpose: defining what it is, stating its current state, and giving usage guidance. It is front-loaded with the 'Beta version' identifier and contains no redundant information.

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

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

The tool is a router with a single natural language question input; the description provides its current status, relationship to the stable version, and experimental behavior. Although there is no output schema, the statement 'same response shape' as ask_pipeworx gives sufficient context for an agent to understand the expected output.

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

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

The schema has 100% description coverage with six aliases for the required 'question' parameter. The description does not add parameter-specific meaning, but since the schema is complete, a 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 identifies the tool as 'Beta version of ask_pipeworx' and explains it is a universal router with the same tools, arguments, and response shape. It distinguishes from the sibling ask_pipeworx by emphasizing its experimental nature and candidate routing improvements.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It implies that if you don't need the newest routing, the stable version is preferable, though it doesn't state this exclusion directly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond these: it reveals the refusal reason taxonomy (not_in_source, no_tool_match, etc.), the return shape including evidence as a verbatim quote, and the fact that it costs one extra LLM call. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by a clear mechanism, return format, usage guidance, and cost tradeoff. Every sentence carries substantive information; there is no filler or redundancy. Despite its length, it remains tightly structured and skimmable.

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

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

There is no output schema, but the description fully compensates by detailing the exact return object on success and failure, including all possible refusal_reason values. It covers the tool's behavior in edge cases like data truncation or tool errors and explains the relationship to ask_pipeworx. For a read-only query tool, 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?

Schema description coverage is 100% with all parameters documented as aliases for 'question'. The description adds context by explaining that the question is used to fill arguments for the underlying routed tools, giving meaning to why only a natural-language question is needed. While it doesn't detail parameter constraints, the schema already covers those adequately.

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 'Hallucination-resistant answer mode for high-stakes reads', which clearly states the tool's specific purpose. It goes on to explain the exact process: routing to other tools, filling arguments, fetching data, and then extracting the answer only from the tool result. This explicitly distinguishes it from its sibling 'ask_pipeworx' by emphasizing the grounded extraction and refusal behavior.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and gives concrete examples like financial verdicts and legal claims. Also provides the alternative: 'prefer ask_pipeworx for casual lookups', and notes the extra LLM call cost. This is textbook usage guidance.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) align with description. Description goes far beyond: details resolution, classification, fan-out, response shapes, safety checks, cancellation rules, parent_event extractor, news fallback fields. No contradictions; full transparency.

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

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

Description is long but well-structured with front-loaded purpose and usage, followed by organized details (classifiers, fan-out, response shapes, safety). Every sentence earns its place; no fluff. Could be slightly more concise but complexity justifies 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?

No output schema, but description thoroughly covers response structure (result.market, analysis, evidence), resolver contract (confidence, alternatives, suggestions), parent_event, news fields, and edge cases (closed markets, low confidence, wide spreads, cancellation rules). Complete enough for effective agent decision-making.

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

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

Schema coverage is 100% with descriptions for all 3 params. Description adds significant value: examples for market (slug, URL, question text), quick vs thorough for depth, and default false with use-case for include_raw. Slightly verbose but clearly explains each param's role beyond schema.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. It distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by being a comprehensive data-gathering tool. The verb 'research' and specific resource 'Polymarket bet' make 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?

Explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also provides when-not-to-use via low-confidence match warning, closed market handling, and wide-spread illiquidity note. Instructions to inspect market_match_confidence before trusting analysis block further clarify safe usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant context: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), explains fiscal year handling, mentions result sorting by primary metric, and describes output format (paired data + citation URIs). This goes well 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 a single paragraph that packs essential information efficiently. It front-loads trigger phrases and then provides details. While not broken into sections, every sentence contributes value without redundancy.

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

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

The description explains what the tool does, what data it pulls for each entity type, how results are sorted, and the output format (paired data with citations). It also highlights efficiency gains (replacing 8-15 lookups). No output schema exists, so the description must cover return values, which it does adequately.

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

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

Input schema covers both parameters with descriptions (type enum and values format). The description adds extra meaning by specifying data source behavior for each type and mentioning constraints like max 5 items. Since schema coverage is 100%, the baseline is 3, but the description provides additional useful semantics.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single call, with specific trigger phrases and examples. It distinguishes from sequential lookups, which are 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 explicitly advises preferring this tool over sequential single-pack lookups when comparing entities, and provides natural language triggers (e.g., 'which is bigger'). It lacks explicit when-not-to-use guidance, but the context strongly implies it is for comparisons, not single entity 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?

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial context: account/paid plan requirements, returned findings packet structure, explicit gaps[] for unanswered facets, citation_uri only when fetchable, contradictions[] on standard/thorough, semantic excerpting, and expected latency. This goes far 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 long but logically organized: account prerequisites, core capability, use-case guidance, depth semantics, output packet details, citation behavior, and performance expectations. Every clause serves a distinct purpose and no filler or tautology is present.

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 specifies the return payload (evidence, confidence, source, fetched_at, citation, gaps, contradictions), error/empty behavior, depth-specific iterations, account requirements, and timing. It is comprehensive enough for an agent to invoke the tool correctly without guessing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful detail about the depth enum (quick/standard/thorough with facet counts and hop behavior) and elaborates on the question parameter's suitability for broad/multi-part queries. This exceeds the schema's explanations.

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 1455 STRUCTURED data sources...' in one call, with an explicit contrast to 'open-web search'. It distinguishes from siblings by naming ask_pipeworx as the alternative for simpler lookups, making the purpose and scope immediately clear.

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also specifies a fallback for non-signed-in users, covering when to use and when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool is safe. The description adds valuable behavioral details: returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and states results are 'ready to call directly, no second schema lookup needed.' This goes beyond annotations.

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

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

The description is concise and well-structured: it opens with the core purpose, follows with usage guidance, and ends with what the tool returns. Every sentence adds value without redundancy.

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

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

Although no output schema is provided, the description explains the return format comprehensively (tool names, descriptions, schemas with examples). Given the tool's meta-nature and the rich sibling context, the description fully equips the agent to use it correctly.

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

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

Schema coverage is 100% with descriptions for all 6 parameters, so baseline is 3. The description adds context by listing aliases (task, q, search, description) and providing examples, which helps the agent understand parameter flexibility. This moves the score to 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('discover') and resource ('tools') and effectively distinguishes itself from sibling tools by positioning itself as a discovery meta-tool to be called first.

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

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

Provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly differentiates from siblings and sets expectations.

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, openWorldHint, idempotentHint), the description reveals that the tool fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, and mentions a sunset for the patents API (soft-fails until reactivated). 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 moderately long but well-structured, starting with examples and then detailing outputs and limitations. Every sentence serves a purpose; minor verbosity is acceptable given the tool's complexity.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description comprehensively covers return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and states limitations (patents soft-fail, names not supported). It fully equips the agent to understand the tool's capabilities.

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

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

Schema coverage is 100% with both parameters described. The description reinforces input format (ticker or zero-padded CIK) and adds context (names not supported, use resolve_entity). This adds value beyond the schema, though the schema already handles type validation.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company' with specific examples like 'tell me about X' and 'company profile for Microsoft'. It distinguishes itself from chaining single-pack lookups, making the purpose unambiguous.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It details input requirements (ticker or CIK, not names) and directs users to resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use 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 destructiveHint=true, so the description reinforces that. It adds useful context about use cases (stale context, task completion, clearing sensitive data). No contradictions.

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

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

Extremely concise with only two sentences, front-loaded with the action and resource.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, usage, and context adequately.

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

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

Schema coverage is 100% with clear parameter description. The description does not add meaning beyond the schema for the single parameter.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key'. It distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when to use this tool: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and suggests pairing with siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description adds behavioral details about fetching the page, extracting title/description/key links, and emitting markdown format, which aligns with and enriches the annotation profile.

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

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

Three concise sentences that front-load the main purpose, then detail functionality and use cases. No fluff or unnecessary repetition; every sentence adds value.

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

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

Given only two parameters, no output schema, and full parameter coverage in schema, the description completely explains the tool's behavior, output format, and appropriate use cases, leaving no significant gaps.

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

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

Schema covers both parameters (url, max_links) with descriptions, but the descriptive text adds meaning by explaining that the URL is for summarizing and max_links controls link entries, and it contextualizes the extraction process (title/description/key links). This goes beyond schema descriptions.

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

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

The description states a specific verb and resource ('Generate a production-ready llms.txt file for any URL'), clearly distinguishing it from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than analysis or scanning.

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

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

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing context for when to use. It does not explicitly state when not to use or name alternatives, but the context is clear enough.

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

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

The description adds value beyond annotations by specifying the data source, input resolution (names auto-resolved), and output structure (season splits with career totals).

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

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

The description is a single, well-structured paragraph with no wasted words, front-loading the core purpose and key details.

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

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

Given the simple 3-parameter schema and no output schema, the description covers input, output, and behavior adequately for an agent to use the tool correctly.

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

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

With 100% schema coverage, the description adds context like automatic name resolution and output details, surpassing the baseline of 3.

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

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

The description clearly states it provides MLB batter-vs-pitcher history with concrete examples and distinguishes it from sibling tools like get_player_stats by focusing on head-to-head matchups.

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 purpose implies usage for head-to-head stats, but there is no explicit guidance on when to use this tool over alternatives or prerequisites, earning a baseline 'implied usage' score.

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. Description adds context about data source (MLB Stats API) and specific fields returned, which is valuable but not critical beyond annotations.

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

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

Two sentences, waste-free. First sentence states purpose and fields, second gives alternatives. Front-loaded and efficient.

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

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

Output schema present, so return values are documented. Description covers what data is returned, source, and alternatives. Complete for a read-only profile 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?

Only one parameter (person_id) with 100% schema description coverage. The description includes an example value but adds no extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it returns a 'Player biographical profile' and lists specific fields (name, number, birth date, age, etc.). It distinguishes from siblings by explicitly naming get_player_stats and get_matchup.

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 alternatives: 'For season statistics use get_player_stats; for batter-vs-pitcher history use get_matchup.' This explicitly tells when to use other tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining automatic name resolution, optional season defaulting to current, and that the tool returns hitting and/or pitching totals from the official MLB Stats API. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the key guidance 'PREFER OVER WEB SEARCH'. The second sentence is dense but efficient, packing parameter details and return values. Minor room for improvement in brevity, but overall concise and well-structured.

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

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

For a simple stats retrieval tool with 3 parameters and no output schema, the description covers return values (hitting and pitching stats) sufficiently. It does not mention error handling or edge cases, but annotations cover idempotency and safety. Complete enough for effective use.

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

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

Schema coverage is 100%, but description adds significant meaning: 'player' can be a name (resolved automatically) or numeric ID, 'season' defaults to current, and 'group' optional with behavior for two-way players. This goes well beyond the schema descriptions, which only list types.

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

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

Description clearly states it retrieves MLB player season statistics, with specific examples like 'how many home runs does Yordan Alvarez have this season'. The verb 'get' and resource 'player stats' are explicit. It distinguishes from sibling tools like 'get_player' and 'get_matchup' by emphasizing season statistics and preference over web search.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH for MLB player SEASON STATISTICS', providing a clear when-to-use directive. Examples of queries (e.g., 'Gerrit Cole ERA in 2025') illustrate appropriate usage. It does not explicitly state when not to use, but the guidance is strong.

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 context about the data source (official MLB Stats API) and output fields, beyond the annotations which already indicate read-only, idempotent, and non-destructive behavior. 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?

Single sentence that is front-loaded with the action ('Active roster for an MLB team') and efficiently conveys purpose and output. No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers the essential aspects: source, output fields, and required parameter. Minor gap: no mention of season or timeframe, but adequate for the task.

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

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

The schema coverage is 100% with a clear description for team_id. The description adds minimal additional meaning (e.g., 'active roster for an MLB team'), but the parameter semantics are already well-defined in the schema.

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

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

The description clearly states it returns the active roster for an MLB team from the official MLB Stats API, listing specific fields (id, name, jersey number, position). This distinguishes it from sibling tools like get_player or get_teams.

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

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

The description implies usage for fetching an active roster, but does not explicitly state when to use it vs alternatives or any prerequisites. It lacks exclusion criteria or alternative suggestions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to restate safety. It adds value by specifying the data source (official MLB Stats API) and the return fields, which aids in understanding 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?

Two sentences cover purpose, source, return fields, and parameter usage. No extraneous information, and the most important details come first.

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 simple tool (one optional param, no output schema), the description adequately explains what is returned and how to use it. Combined with annotations covering safety, it is fully complete for an agent to decide and invoke correctly.

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

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

The input schema has 100% coverage for the single parameter 'date', with a clear description. The tool description adds no extra meaning beyond what the schema provides, so 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 it returns MLB daily schedule and scores, listing specific data fields (teams, scores, status, venue). This verb+resource structure distinguishes it from sibling tools like get_player or get_matchup.

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

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

The description explicitly says to pass a date or omit for today's games, giving clear usage context. It does not mention when not to use or alternative tools, but the single parameter makes it straightforward.

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, so the bar is lower. The description adds valuable behavioral context: returns specific fields (wins, losses, win percentage, games back, division rank, streak), groups by league/division, and defaults to current season. This goes beyond simple safety traits and informs the agent about data scope and 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 three sentences, each earning its place: the first gives a clear usage preference, the second details what it returns and grouping, the third clarifies default and parameter semantics. It is front-loaded with actionable guidance and contains no filler.

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

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

Given the tool's simplicity and rich annotations/schema, the description covers the main context: purpose, return fields, grouping, and parameter defaults. There is no output schema, but the description sufficiently describes what to expect. A minor gap is not specifying response format, but that is not critical for this read-only data tool.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (season, league_id). The description reinforces the season usage ('pass season only for a past year') but does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves MLB division standings from the official MLB Stats API, with a specific verb and resource. It distinguishes itself from web search and other sibling tools by focusing on standings and team records, including specific metrics returned (wins, losses, games back).

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 'PREFER OVER WEB SEARCH' for MLB standings/records, gives example queries, and clarifies when to use the season parameter vs. defaulting to the current season. This provides clear when-to-use guidance without ambiguity.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. The description adds that it uses the official MLB Stats API and returns specific fields, but does not elaborate on rate limits or data freshness.

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

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

Two concise sentences, front-loaded with the action and resource, 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 no output schema and zero parameters, the description sufficiently covers expected return values and source. Minor missing context like pagination or ordering is not critical.

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 has no parameters (100% coverage), so description adds value by listing output fields, which aids understanding.

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

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

The description clearly states the tool lists all MLB teams and specifies the returned fields (id, name, abbreviation, location, league, division, home venue). It distinguishes itself from sibling tools by its unique 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 implies the tool is for listing teams when no filtering is needed, but does not explicitly state when to use alternatives or provide exclusions.

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

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

Annotations already indicate safe read. Description adds return fields and default behavior (active only), complementing annotations well.

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

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

Two concise sentences, front-loaded with purpose, 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?

Lists return fields compensating for lack of output schema. Context with siblings is adequate, though parameter description is missing.

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

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

Schema covers parameter fully. Description implies default but adds no new info beyond schema.

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

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

Clearly states it lists the caller's active subscriptions and specifies return fields. Distinguishes from subscribe/unsubscribe siblings.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use 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 only provide false hints, so the description carries the disclosure burden. It discloses the claim_token return flow, rate-limiting (5 per identifier per day), quota-free status, and that the team reads digests daily. This adds meaningful behavioral context beyond annotations, though it doesn't explicitly describe the persistence mechanism of the feedback itself.

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: purpose, usage categories, exclusions, claim_token mechanism, rate limits, and quota-free note. It is front-loaded with the core purpose and structured logically without wasted words.

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

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

For a tool with no output schema, 4 parameters (including a nested object), and a multi-stage claim_token flow, the description covers all necessary aspects: when to use, what to include, how to retrieve results, limitations, and next steps. It is fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some guidance around claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advises how to frame the message, but it largely reinforces what the schema already documents.

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 directive: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and explicitly differentiates from sibling tools by noting it is only for tools served by this Pipeworx connection, not other MCP servers.

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 conditions for each category (bug, feature/data_gap, praise) and an explicit when-not-to-use case (tool from a different MCP server) with a fallback heuristic ('Not sure? Pipeworx tool names are the ones this connection lists'). This is exemplary usage guidance.

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

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

Annotations already mark it as read-only and idempotent. The description adds value by disclosing that data is derived from CF analytics-engine, contains no PII, and is cached (5min-1h), which helps the agent understand freshness and behavior beyond what annotations provide.

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

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

The description is well-structured with a purpose sentence, bulleted use cases, and additional behavioral details. It is front-loaded and every sentence serves a purpose, though it could be slightly shorter without losing clarity.

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

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

Given the single optional parameter, good annotations, and no output schema, the description effectively covers return type, caching, and use cases. It could be more explicit about the exact output structure (e.g., format of 'top tools') but overall provides sufficient context for an AI agent.

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

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

The input schema has 100% coverage with parameter descriptions. The tool description reiterates the same information about the 'window' parameter (e.g., '24h,7d,30d') but does not add new semantic meaning beyond what the schema already provides, so a 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 states it returns 'top tools, top packs, and total call volume' over a window, which is specific and clearly distinguishes it from siblings like 'discover_tools' that might have different scop es.

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 lists three explicit use cases (e.g., discovering hot data sources, confirming a canonical tool), providing clear context for when to use. However, it does not explicitly mention when not to use or directly compare 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes beyond by detailing partition checks, Jaccard similarity filter, placeholder filter, fill check against CLOB depth, and the condition that realizable_edge_pp <= 0 means 'do not trade'. 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 front-loaded with the purpose and mode summary. It is verbose but well-structured with clear sections for each mode and special topics (semantic anchor, partition filter, fill check). A bit lengthy, but 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?

Given no output schema and complex behavior, the description explains the response structure (opportunities[], partition_check, fill check), the logic for cross-event scanning, and the conditions that filter results. It covers all major aspects an agent needs to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial value: examples of slugs and seed questions, and explains the behavior triggered by each parameter (event mode vs topic mode). This enriches the schema information significantly.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and references sibling tools like polymarket_fill_risk, making the purpose unambiguous and differentiated.

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 guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It also recommends event mode and warns about fill check conditions. However, it does not explicitly list scenarios to avoid.

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 rich behavioral details beyond the annotations, such as model families (lognormal, GDELT, etc.), edge calculation logic (edge_pp_net after slippage), response structure (by_segment with diagnostics), caching at KV level, and caveats (e.g., Fed bets unreliability). This adds significant value beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is lengthy (over 200 words) but every sentence adds value. It is well-structured, starting with purpose, then model details, response format, and parameter guidance. It could be slightly more concise by grouping some details, but the complexity justifies the length.

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

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

Given the tool's complexity (9 parameters, 3 segments, diagnostics, model explanations, caching), the description is thoroughly complete. It explains what each segment yields, what data each opportunity contains, edge calculation, filtering knobs, and diagnostic feedback for empty results. No output schema exists, but the description compensates adequately.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds meaning beyond the schema by explaining the purpose of key parameters like min_partition_leg_kelly and the tradeable-edge knobs (min_liquidity, max_spread_pp). It provides context that helps interpret parameter values, particularly for the complex partition-related filters.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also frames it as 'Built for "what should I bet on today" — agents discover opportunities,' which is a specific verb+resource and differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states when to use the tool: 'for what should I bet on today' and discusses caching behavior. It implies usage for discovering opportunities but does not provide explicit when-not-to-use or alternatives among the many sibling tools. The context is clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=False. Description adds useful context about data sources (daily snapshots), time limits (60-day TTL), and caveats (decay from daily closes, not intraday, gaps in snapshots). No contradiction with annotations.

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

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

Description is informative and relatively concise given the complexity, front-loading purpose and providing detailed response structure. A bit dense but each sentence adds value.

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

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

For a tool with no output schema, description thoroughly explains response fields (tracked, expired, snapshot_dates) and limitations (TTL, gaps). Parameters are well-described. Completes all needed context for an AI agent to use it correctly.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds defaults (14, '1wk') and clamp (2-30 for days) and explains their role in lookback and snapshot family, providing context beyond schema.

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

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

Description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, using specific verbs like 'answers how long has this edge existed and is it shrinking?' It distinguishes from sibling tool polymarket_edges by focusing on historical persistence rather than current 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?

Description explains the tool's purpose with a concrete question and example, implicitly guiding when to use it (for historical edge analysis). It does not explicitly state when not to use it or contrast with all siblings, but context is strong enough for an agent to infer correct usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds operational details: walks order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and explains basket behavior (theoretical_sum vs realizable_sum, thin_legs, forced directional risk). No contradiction with annotations. The description enriches transparency beyond the annotation safety profile.

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

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

The description is well-structured with clear sections (single-market, basket) and front-loaded with the core purpose. While it is lengthy, every sentence provides useful context for a complex tool. It could be slightly more concise, but it is well-organized and informative.

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

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

Given the tool's complexity (two modes, four parameters, no output schema), the description is exceptionally complete. It explains return values for both modes (e.g., top_of_book, vwap, verdict, capture_ratio, profit_usd, per-leg fill detail), addresses edge cases (thin_legs, forced_directional_risk), and provides practical usage notes. No essential 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?

Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning: explains the default behavior for side in basket mode (auto based on partition sum) and clarifies the interpretation of size_usd for single-market vs basket. This adds value beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates between single-market and basket modes and explicitly links to sibling tools (polymarket_arbitrage, polymarket_edges) by advising to use this tool before acting on their signals, establishing distinct usage scope.

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

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

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 why (theoretical overround not capturable on thin books, partial fills convert arb to directional risk) and clarifies parameter requirements ('REQUIRES one of market or event').

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 substantial behavioral context beyond annotations: explains safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), the meaning of matched_pairs:0 scenarios, and the risk of non-equivalent bet shapes. This is exhaustive and transparent.

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

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

The description is verbose but well-structured with bold headings for modes, response, and safety fields. It front-loads key information and uses clear formatting, though it could be slightly more concise.

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

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

Given the tool's complexity (no output schema, multiple modes, safety warnings), the description is highly complete. It covers all necessary aspects: modes, output structure, safety fields, and caveats about non-tradeable spreads.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage). The description further explains the topic shortcuts and the override behavior of explicit tickers, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons, and specifies two modes (topic shortcuts and explicit tickers).

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

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

The description provides clear guidance on when to use topic vs. explicit modes, and warns that pre-mapped topics often yield compatibility warnings. However, it does not explicitly state when not to use the tool (e.g., for single-venue analysis).

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds scoping context ('Scoped to your identifier') and explains the behavior when key is omitted. No contradictions.

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

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

Three sentences, front-loaded with main action, followed by usage context and scoping. Every sentence is informative and necessary.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, usage, scoping, and relationships to siblings. No gaps.

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

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

Schema coverage is 100% and the description expands on the parameter behavior, explaining the effect of omitting the key (list all) and giving real-world examples of keys. Adds meaning beyond schema.

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

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

The description clearly states the tool's function: retrieve a saved value or list all keys. It uses specific verbs ('retrieve', 'list') and explicitly distinguishes from sibling tools 'remember' and 'forget' by referencing them.

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 concrete examples of when to use ('look up context stored earlier') and explicitly pairs with 'remember' and 'forget', giving clear guidance on 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 context beyond annotations by detailing the side effect of mark_read (flagging as read), the fields returned, and polling suitability. There is a potential contradiction with idempotentHint, but the description is more accurate.

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 only 3-4 sentences, front-loaded with the primary purpose, and every sentence adds value without redundancy.

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

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

The description covers the main aspects of the tool given the absence of an output schema: lists returned fields, filtering, and mark_read. It lacks explicit mention of ordering or pagination, but is sufficient for a feed-pull tool.

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

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

Schema coverage is 100%, and the description adds meaning with examples (type filter with 'sec_8k', ISO timestamp format, mark_read behavior) beyond the schema descriptions.

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

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

The description starts with 'Pull fired events from your subscription feed' and specifies what is returned (source, citation_uri, payload). It clearly states the verb and resource, and the uniqueness is evident from the sibling list.

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 context for filtering and the mark_read option, and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool vs alternatives.

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

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

Annotations declare readOnly, idempotent, and non-destructive. The description adds valuable context: parallel fan-out to SEC, GDELT, USPTO with a fallback (GDELT→GNews), soft-fail for USPTO, and return structure (changes[] grouped by source + total_changes + citation URIs). This goes beyond annotations, though more details on error handling could improve it.

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 compact paragraph (about 5 sentences) with no redundant information. It is front-loaded with example queries to quickly convey purpose, and every sentence adds essential detail.

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 moderate complexity (multiple sources, fallback, parameter formats, no output schema), the description covers all key aspects: input formats, source behavior, return structure, and distinction from sibling. It is self-contained enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds usage context: 'since' accepts ISO or relative shorthand with examples, 'type' is restricted to 'company', and 'value' can be ticker or CIK. This reinforces and provides practical guidance beyond the schema.

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

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

The description opens with representative queries ('What's new with X') and states clearly: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the verb (retrieve changes) and resource (company), and distinguishes from the sibling tool entity_profile for static profiles.

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

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

Explicit guidance is given: 'Use entity_profile instead when you want the static profile...' It explains when to use (monitoring changes over a window) and when not to, and provides parameter usage examples (e.g., use '30d' for typical monitoring).

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

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

Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) already indicate write-safe behavior. The description adds scoping by identifier and persistence duration (24 hours for anonymous sessions), which goes beyond annotations. However, it doesn't explicitly mention that re-saving with the same key overwrites, though idempotentHint implies it.

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

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

Four sentences, each earning its place: purpose, usage, behavior, pairing. Front-loaded with the core action. No unnecessary words.

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

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

Given no output schema, the description adequately covers what is stored and scoping. It could mention size limits or conflict behavior, but overall it is complete enough for a simple key-value store 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?

With 100% schema description coverage, the description adds value by providing naming conventions for keys (e.g., 'subject_property', 'target_ticker') and clarifying that value is freeform text. This goes beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and explicitly distinguishes from siblings like 'forget' and 'recall' by mentioning pairing with them.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and includes examples of use cases (resolved ticker, target address, user preference). Also explains scoping and persistence differences for authenticated vs anonymous sessions.

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, the description discloses that the tool cascades through multiple lookup endpoints, degrades gracefully if sources unavailable, labels identifiers with provenance, explicitly reports unresolved identifiers, and describes the ownership tree fields. This is rich behavioral context that helps 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 front-loaded with examples and a clear purpose. The SUPPORTED TYPES section organizes two distinct behaviors. It is longer than minimal but every sentence contributes; a more structured format would improve scanability.

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

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

Given no output schema, the description covers the input parameters, types, output fields (CIK, ticker, LEI, FIGI, RxCUI, etc.), and edge cases like source unavailability. It provides a complete picture of the tool's behavior.

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

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

The schema already documents both parameters, and the description enhances them: for `value`, it specifies input formats per entity type (ticker, CIK, name for company; brand/generic for drug) and gives examples. It also explains the meaning of `type` with the outputs associated with each enum 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 concrete user queries ('What's the ticker for…') then states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes itself by noting 'Use FIRST whenever you have a name but need an ID.' This goes beyond a generic statement and clearly differentiates 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?

It explicitly instructs to use the tool first when a name is present but an ID is needed, and provides example query patterns. It also notes that one call 'replaces 2-3 manual lookups,' which gives an efficiency rationale. Although it doesn't name alternative tools, the guidance is enough for when to invoke.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds: probes via 'ai_visibility_check', ranks by score, surfaces most/least recognized, and return includes score, confidence, signal density—adding value beyond annotations.

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

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

Three sentences, front-loaded purpose, each sentence adds value. No redundant or vague phrasing.

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

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

No output schema, but description explains return format (ranked list with fields). Parameters fully covered by schema and description. Context signals indicate high coverage. Complete for a comparison 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 has 100% description coverage, but description adds key nuance: first entity treated as 'subject' for narrative, and implies default model. This clarifies parameter semantics beyond schema.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, distinguishes from sibling 'ai_visibility_check' by specifying multi-entity comparison and ranking.

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

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

Provides a concrete use case (competitive AI-marketing audits) and implies when to use this vs 'ai_visibility_check' (single vs multi). Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list if timeout occurs. No contradiction.

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

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

Description is a single paragraph but well-structured. It front-loads the main purpose and then provides details. Could be slightly more concise but every sentence adds value.

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

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

Despite no output schema, the description fully documents the return fields and structure, including a summary block, per-advisory details, links, and alternatives. Also covers edge cases like partial failures. Complete for a tool with only 2 simple parameters.

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

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

Schema coverage is 100% so baseline is 3. Description adds value by noting scoped packages are accepted for the package parameter, and confirms version defaults to latest when omitted. This extra context justifies a 4.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia to answer safety, popularity, and size questions. It specifies the NPM ecosystem scope and differentiates from other tools.

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

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

Explicitly tells when to use: 'when an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also mentions alternatives for other ecosystems (PyPI, Maven, etc.) via deps.dev:version directly.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K chars), truncation behavior, and offset details for verbatim quotes.

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 and well-structured: purpose, usage, technical details. Every sentence adds value without redundancy. Front-loaded with the key action.

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

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

For a tool with 3 parameters, full schema coverage, and no output schema, the description covers what the tool does, when to use it, technical details, and pairing with sibling tools. It is fully sufficient.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing natural-language query examples (e.g., 'supply-chain risk') and clarifying the limit default (5). This enhances understanding beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining that it searches within a provided text.

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

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

The description explicitly states when to use: when the record is too big for the prompt, and pairs with ask_pipeworx_grounded for grounding. It provides clear guidance and an alternative 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 states it creates a new subscription each time, which contradicts the annotation idempotentHint=true. According to instructions, score 1 when description contradicts annotations.

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

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

The description is well-structured: first sentence states the core action, then authentication requirements, then detailed type and delivery information. Every sentence adds value; no fluff. It is appropriately sized given the tool's complexity.

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

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

Despite no output schema, the description fully covers the return (subscription ID), authentication constraints, all five subscription types with parameter examples, delivery channel options with limitations, and webhook signing details. This is comprehensive for a create subscription 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 description adds significant meaning beyond the schema: it provides concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topic), explains delivery channel constraints (SMS cap, webhook HMAC), and clarifies required fields for clinical_trial. With schema coverage at 100%, baseline is 3, but the description's rich details earn a 5.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription ID. It lists supported subscription types and delivery channels, distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description implies when to use (to start monitoring) and mentions authentication requirements (Pipeworx OAuth), but does not explicitly contrast with sibling tools or state when not to use it. However, the context and siblings make the usage clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about return format (questions with tool + argument shape) and optional topic focus, but doesn't 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?

Description is fairly long but packed with useful information. Front-loaded with synonyms and purpose. Could be slightly more concise, but no filler.

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

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

Given no output schema, description explains return value well (category-bucketed example questions with tool + argument shape). Covers use cases, arguments, and context. 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 has 100% coverage for the single parameter 'topic'. Description adds examples of values and says 'Omit for a cross-category spread', providing extra meaning beyond schema.

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

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

Description clearly states it's the onboarding entry point, returns category-bucketed example questions, and can focus on a topic. Distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by being about what questions to ask.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides clear when-to-use 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 adds behavioral details beyond annotations: it clarifies that the subscription is deactivated (not deleted), which is consistent with destructiveHint=false. It also mentions ownership enforcement. No contradiction with annotations (readOnlyHint=false, 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 sentences, no wasted words. Key information is front-loaded: action, ownership, and behavioral detail are all present in a compact form.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary aspects: purpose, ownership, behavioral effect (deactivation), and consequence for historical data. It is fully self-contained.

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

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

The schema already describes the parameter well (Subscription id (uuid)). The description adds context that the id is 'returned by subscribe', which helps the agent understand the source. Schema coverage is 100%, so the baseline is high.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use the tool. It also explains that the row is deactivated not deleted, indicating that historical events remain available via recent_alerts. No explicit alternatives are named, but the context is clear.

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

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

Beyond the readOnly/idempotent annotations, it explains the return verdict set, the meaning of could_not_verify (check did not happen, not evidence), and unsupported (no source covered). It also discloses the two execution paths (SEC EDGAR structured and grounded pipeline), which is valuable behavioral context.

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

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

Despite being dense, the description front-loads example intents, then explains behavior, error semantics, and efficiency in a structured way. No sentence is wasted; the tradeoff of 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?

Since no output schema is present, the description compensates by enumerating the verdict values, the payload (actual value + citation + reasoning), and distinguishing error states. It also explains the two-path execution and the semantics of the responses, making the tool self-contained for an agent.

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

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

The input schema already documents both parameters comprehensively, so the description carries no extra parameter semantics; it only reinforces the claim example. The mention of 'exact percent-delta math' hints at tolerance behavior but adds little beyond the schema's tolerance_pct 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 opens with canonical user phrasings and explicitly states it performs 'natural-language claim verification against authoritative sources,' clearly distinguishing it from general research or search sibling tools. It also specifies financial vs non-financial routing, making the tool's purpose concrete.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear invocation condition. It differentiates between company-financial claims and other claims but does not name specific sibling tools as alternatives or define explicit exclusions.

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