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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond the annotations: it routes internally across 5,767 tools, automatically fills arguments, and returns structured answers with stable citation URIs. This gives the agent a clear model of what happens when the tool is invoked.

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 a strong directive and useful domain coverage, but it is long and somewhat repetitive, repeating the web-search comparison twice ('PREFER OVER WEB SEARCH' and 'even if web search could also answer it'). The example list is helpful, but the redundancy and length reduce conciseness.

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

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

For a complex router tool with no output schema, the description covers the return format (structured answer with stable pipeworx:// citation URIs), the scope of supported data domains, typical question phrasing, and when to use sibling tools. The agent has enough context to invoke the tool correctly in most factual-question scenarios.

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

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

All six parameters are documented in the input schema as aliases of the single required 'question' parameter, so schema description coverage is 100%. The description's examples reinforce natural-language usage but do not add new parameter semantics beyond what the schema already states.

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

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

The description uses specific verbs and nouns: it routes a question to one of 5,767 tools, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It clearly establishes the tool as a general-purpose factual-research router and distinguishes it from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this over web search for many data categories, supplies trigger phrases like 'look up' and 'get the latest', and gives concrete examples. It also names alternatives with conditions: ask_pipeworx_grounded for single well-scoped questions and deep_research for broad/multi-part questions, so an agent knows when to pick this tool versus its siblings.

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

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

Beyond the annotations, it discloses that routing improvements can be live during tests, that none is active as of 2026-07-26, and that this is a full working router rather than a thin fallback. It also states the response shape matches ask_pipeworx exactly, which is meaningful behavioral context. This goes well beyond what the annotations alone 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 front-loaded with the core identity and current status, then gives usage direction and a reassurance about full functionality. It is a bit longer than strictly necessary, with some repetition of the idea that it currently matches ask_pipeworx exactly. Overall, every sentence contributes useful information.

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

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

For a tool with one required, well-documented parameter and safety annotations, the description covers current behavior, experimental nature, and full working status. It does not independently describe the response format, but it references ask_pipeworx's response shape as equivalent. This is reasonably complete in context.

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

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

The schema already documents all parameters, including the required question field and aliases like q, text, input, and prompt, with 100% coverage. The description adds only that the arguments are the same as ask_pipeworx, which provides no additional semantic detail. Baseline 3 is appropriate because the schema carries the parameter information.

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

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

The description clearly identifies the tool as a beta variant of ask_pipeworx: an identical universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable router by mentioning candidate routing improvements under test. It still relies somewhat on the agent already understanding what ask_pipeworx does, which keeps it from a 5.

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 says to use it exactly like ask_pipeworx when wanting the newest routing, and clarifies that no candidate is currently active so behavior matches stable. It also explains that results are compared against the stable router to decide merges. It does not explicitly spell out when to prefer stable ask_pipeworx or the grounded variant, but gives sufficient direction for the beta/stable choice.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses substantial behavioral detail: it only extracts from tool results, returns a structured success payload with evidence, and explicitly refuses with defined refusal_reason values when data doesn't directly answer. No contradiction exists between the description and annotations.

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

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

The description is dense but every sentence earns its place: it front-loads the core purpose, explains the routing behavior, enumerates the return and refusal contracts, gives concrete use cases, and provides a cost-based comparison with the sibling. Nothing is redundant.

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

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

Given there is no output schema, the description compensates by fully specifying the success return shape and all refusal reasons. It also covers practical selection context, cost tradeoffs, and use-case fit. An agent has everything needed to invoke the tool correctly and interpret its 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?

Schema description coverage is 100%, with all six parameters documented as aliases for the single required 'question' parameter. The description itself adds no parameter-level detail, but the schema already fully covers semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains that it routes like ask_pipeworx but extracts answers using only tool results. This is a specific verb+resource pairing, and it names the sibling it differentiates from (ask_pipeworx), making the distinction explicit.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives an exclusion condition: 'prefer ask_pipeworx for casual lookups' and explains the cost difference of one extra LLM call. This fully routes the agent to the correct 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 (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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account and paid-tier requirements, parallel facet routing, return packet contents, explicit gaps[] with no invention, hop and citation_uri fetchability, contradictions[], semantic excerpting, and latency expectations. No contradiction with annotations exists.

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

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

The description is dense but well-organized: account requirement and alternatives are front-loaded, followed by purpose, return format, usage, depth behavior, and timing. It loses one point due to noticeable redundancy ('For a single lookup use ask_pipeworx instead' appears twice) and its overall length.

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

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

With no output schema, the description fully covers what the agent will receive: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop, and citation_uri. It also covers auth constraints, depth semantics, and latency, leaving little ambiguity 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 coverage is 100% for both parameters, so the baseline is 3. The description adds value beyond the schema by linking depth values to concrete behavior (gap recovery, lead chasing, paid plan, timing), and by clarifying that the question parameter supports broad/multi-part natural language.

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: grounded multi-source research across Pipeworx's 1,506 structured data sources in one call. It clearly distinguishes itself from open-web search and from ask_pipeworx, making its purpose and scope unambiguous.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data, while directing single lookups and breaking-news queries to ask_pipeworx. It also covers the not-signed-in case and advises a follow-up with ask_pipeworx when gaps appear, which is strong routing guidance.

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

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

Annotations already declare readOnlyHint=true 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?

The description goes well beyond the annotations by disclosing fan-out behavior, return fields, source failure semantics, soft-fails (USPTO sunset), empty-section expectations, and resolution behavior. This is exactly the kind of behavioral context an agent needs to interpret results correctly.

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 the tool is genuinely complex and the length is mostly earned. It front-loads the strongest guidance (prefer over chaining) and then systematically enumerates return sections; a mild structural improvement would be breaking the long paragraph into bullets, but current structure is still navigable.

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

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

For a complex, multi-source tool with no output schema, the description is remarkably complete: it explains input forms, resolution behavior, expected empty results, failure softness, and the precise meaning of each returned section. An agent can invoke this tool and interpret its response without additional context.

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

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

The schema already covers the two parameters at 100%, so the baseline is 3; the description adds value by clarifying private-company resolution behavior and reiterating the interchangeability of `type`. It mostly repeats schema examples, but the resolved:false nuance is meaningful for proper use.

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

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

The description states a specific verb/resource: "full cross-source profile of a US public company in ONE parallel call," with concrete example phrasings. It clearly distinguishes itself from single-source lookups and sibling research tools by emphasizing the holistic, parallel fan-out 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?

Contains an explicit routing rule: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also clarifies expected behavior for private companies (resolved:false), which helps an agent decide whether the tool succeeded or the input is simply out of scope.

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?

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 declare readOnly/idempotent, and the description adds that data comes from the official MLB Stats API and covers both in-progress and completed games, plus the granularity of the lines. It doesn't discuss pagination or error handling, but that's minor here.

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

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

Three sentences, each earning its place: purpose/content, data provenance, and parameter sourcing. No redundant wording.

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 single-parameter read-only tool with no output schema, the description covers what the tool returns, where the ID comes from, and when it applies. Nothing essential is missing for an agent to invoke it.

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 schema already documents game_pk's type and source. The description only repeats that source, adding no new parameter 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 opens with 'MLB BOX SCORE for one game by gamePk' and enumerates the exact batter, pitcher, and team totals returned, making its scope immediately recognizable against siblings like mlb_schedule or mlb_player_game_log.

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

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

It explains that gamePk should come from mlb_schedule, mlb_probable_pitchers, or a mlb_player_game_log row, and notes it works for in-progress and completed games. It doesn't explicitly state when not to use alternatives, but the one-game scope is clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: it uses the official MLB Stats API, automatically resolves batter/pitcher names, and returns season-split hitting lines with career totals. This goes beyond the structured annotations, though it omits potential error or rate-limit 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 compact and front-loaded, using one dense paragraph to cover purpose, input formats, examples, output metrics, and seasonal splitting. No filler or redundant restatement of the tool name.

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 three-parameter tool with no output schema, this description is complete: it explains accepted inputs, automatic name resolution, optional season limiting, and the specific returned hitting statistics. An agent has enough context to call it correctly without requiring additional documentation.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful extras: both batter and pitcher accept names or numeric IDs, names are resolved automatically, and 'season' is optional and controls career-wide versus single-season results. This supplements the schema with practical 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 opening phrase 'MLB BATTER-vs-PITCHER history' states a specific verb-like purpose with a clear resource and scope. Concrete examples like 'how has Yordan Alvarez hit against Tanner Bibee' make it instantly distinguishable from the other MLB sibling tools such as mlb_player_stats or mlb_boxscore.

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

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

The description gives clear context and concrete input examples, making it obvious when to call this tool for batter-versus-pitcher matchups. It does not explicitly name alternatives or state when not to use it, but the purpose is specific enough that an agent can infer appropriate 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that it pulls from the 'official MLB Stats API' and lists the fields, but doesn't disclose any additional behaviors like rate limits, error cases, or data freshness. Given the annotations, this is adequate but not above the baseline.

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, zero filler. The first sentence front-loads the purpose and the returned fields, the second gives usage alternatives. Every clause earns its place.

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

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

For a single-parameter tool returning biographical data, the description fully covers what the agent needs: what it returns, how to use alternatives for stats, and the source. No critical information is missing 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 coverage is 100%, and the description does not add extra meaning about person_id beyond what the schema already provides ('MLB person/player id (e.g. 660271)'). It is a single parameter with clear documentation in the schema, so the description doesn't need to expand further.

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 ('Returns') and a clear resource ('Player biographical profile from the official MLB Stats API'), enumerating the exact fields returned. It also explicitly differentiates from siblings by naming mlb_player_stats, mlb_player_game_log, and mlb_matchup for other data types.

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 routing: 'For season statistics use mlb_player_stats; for per-game form use mlb_player_game_log; for batter-vs-pitcher history use mlb_matchup.' This tells an agent exactly when to pick this tool and when not to.

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

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

Beyond the read-only/idempotent annotations, the description discloses the data source, newest-first ordering, automatic name resolution, season/default-game-count behavior, and the exact fields returned in each row. No contradictions with the annotations; it adds substantial 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?

Four focused sentences: definition, example triggers, invocation contract, and return-field breakdown. Every sentence adds value, and the most important scoping ('per-game', 'newest first') is front-loaded.

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

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

With no output schema, the description carries the burden of describing return values, and it does so thoroughly by enumerating date, opponent, home/away, result, gamePk, and hitting/pitching line fields. Defaults, accepted identifiers, and intended queries are all covered.

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 reinforces automatic name resolution, default season, and default group behavior, but these are already in the schema; no additional parameter semantics are 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 states a specific, unambiguous purpose: per-game batting/pitching lines for an MLB player, newest first, from the official MLB Stats API. This clearly differentiates it from sibling tools like mlb_schedule, mlb_standings, and mlb_player_stats by focusing on game-level logs rather than aggregates or fixtures.

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?

Natural-language examples ('How has Yordan Alvarez hit over his last 10 games', 'Gerrit Cole's last five starts') give clear context for when to invoke the tool. It stops short of explicitly naming alternatives or saying when not to use it, so it earns a strong four rather than a five.

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 state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: automatic name resolution, defaulting to the current season, supporting both hitting and pitching, and citing the official MLB Stats API as the data source.

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, front-loaded with a direct preference directive, and every clause earns its place. Examples, parameter behavior, return fields, and data source are all packed into one tight paragraph with no filler or repetition.

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

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

For a read-only stats lookup with a small parameter set and no output schema, the description covers everything needed: selection context, accepted player formats, season defaulting, optional hitting/pitching grouping, and the specific returned stat categories. An agent can invoke it correctly without digging further.

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

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

The input schema already covers all three parameters with 100% description coverage, so the schema carries the heavy lifting. The tool description reinforces the 'name or person_id' flexibility and season default, but adds no genuinely new param-level detail beyond 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 strong directive — 'PREFER OVER WEB SEARCH for MLB player SEASON STATISTICS' — and then substantiates it with concrete query examples. It names both the resource (player season statistics) and the action (retrieve totals), and the season-stat emphasis clearly separates it from siblings like mlb_player_game_log and mlb_boxscore.

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

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

The description explicitly tells the agent when to reach for this tool instead of web search and gives representative natural-language queries. It could go further by naming sibling tools such as mlb_player_game_log as the alternative for per-game data, but the 'SEASON STATISTICS' framing and example queries give solid selection 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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context: data comes from the official MLB Stats API, lineups are empty until usually 2-4 hours before first pitch, and each game includes status, venue, and gamePk.

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

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

Every sentence earns its place: the first identifies the resource, the second gives concrete example queries, the third describes return contents and timing behavior, and the fourth explains invocation. It is information-dense without redundancy and well front-loaded.

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

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

The tool has only two optional parameters, rich annotations, and no output schema; the description compensates by listing key return fields and the lineup-timing caveat. An agent has enough context to select and invoke the tool correctly in most situations.

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

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

Input schema coverage is 100%, so the schema fully documents both parameters. The description largely restates the same information (date in YYYY-MM-DD, optional team by id or name) rather than adding deeper semantic nuance, matching the baseline for full schema coverage.

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

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

The description clearly states the resource: probable pitchers and posted starting lineups per game for a date, and enriches it with concrete natural-language examples. The unique resource makes it readily distinguishable from sibling MLB tools like mlb_schedule or mlb_boxscore.

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?

Natural-language queries ('who is pitching for the Astros tonight', 'tomorrow's MLB probable starters', 'is <player> in the lineup today') make the intended use cases clear, and it explains date omission and optional team filtering. It does not explicitly contrast with sibling tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds useful context by noting the official MLB Stats API source and the 'active' roster scope, but it does not disclose additional behavioral details such as data freshness, rate limits, or how open-world changes might affect results.

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

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

Two sentences with no filler or repetition. The core purpose is front-loaded, and the return value summary is concise without repeating schema 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?

For a single-parameter, read-only tool with full schema coverage and no output schema, the description provides the necessary return-field context. It does not mention how to obtain team IDs or reference sibling tools, but with the schema example provided this is a minor gap rather than a completeness failure.

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 parameter, team_id, is already documented with type and an example. The description does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource ('Active roster for an MLB team') and the specific operation ('Returns each player with id, name, jersey number, and position abbreviation'). It is distinct from sibling tools like mlb_schedule, mlb_standings, and mlb_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 this should be used when the agent needs an active MLB team roster, and the return fields clarify what is available. However, it does not explicitly distinguish when to choose this over related sibling tools such as mlb_teams or mlb_player, nor does it state any exclusions or alternatives.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's additional note about the official MLB Stats API source and the returned fields adds useful context. This helps the agent anticipate response contents even without an output schema.

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

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

Two sentences with no filler. The main purpose and return contents are front-loaded, and the parameter instruction is concise and immediately actionable.

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 single-optional-parameter tool with strong annotations and no output schema, the description covers the essential call pattern, return fields, and data source. Minor omissions like timezone or date-range limits are not critical for this simple read-only 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 schema fully describes the single optional 'date' parameter with format and omission behavior. The description repeats this rather than adding new semantic detail, so the schema carries the burden and the baseline of 3 applies.

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

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

The description clearly states the tool provides the MLB daily schedule and scores, and specifies returned content (teams, scores, status, venue). It does not explicitly contrast with sibling tools like mlb_boxscore or mlb_standings, but 'daily schedule' is a sufficiently distinct 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 explains how to pass an optional date, but gives no guidance on when to choose this tool over sibling tools. There is no mention of alternatives, exclusions, or conditions like 'use mlb_boxscore for a single game detail'.

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 openWorldHint, so the safety profile is known. The description adds useful behavioral context: it defaults to the current season, only accepts a past season in `season`, returns grouped league/division standings, and lists the computed metrics. 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 three sentences with no filler. The strongest guidance ('PREFER OVER WEB SEARCH') is front-loaded, followed by examples, data scope, output fields, and default behavior. Every sentence earns its place.

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

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

Despite having no output schema, the description lists the returned fields (wins, losses, win percentage, games back, division rank, streak) and explains grouping. Combined with the fully documented parameters, this is sufficient for an agent to invoke the tool correctly for standings queries.

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 both `season` and `league_id` already fully documented including defaults and examples. The description reinforces that `season` should be omitted for the current year, but it does not add substantial meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description is highly specific: it identifies the resource as 'MLB division standings (regular season)' from the official MLB Stats API, and gives concrete example queries like 'current NL West standings' and 'how many games back are the Mets'. This clearly differentiates the tool from sibling mlb_boxscore, mlb_schedule, or mlb_player tools by naming the exact data domain.

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 says to prefer this tool over web search for standings and team records, providing example user intents. It does not enumerate exclusions or explicitly contrast with sibling MLB tools, but the usage context is unmistakable and actionable.

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 establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral detail by stating the data comes from the official MLB Stats API and that the result is a list of team objects with specific fields. No contradictions with annotations were found.

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 short sentences with no filler. The primary action and scope are front-loaded, and the field list is compact and useful.

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 zero-parameter read-only list tool, the description is largely complete, including return fields. The only minor gap is ambiguity around whether 'all MLB teams' means current active teams or includes historical franchises, which an agent may need to disambiguate.

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 tool takes zero parameters, so the description has no parameter burden to carry. The schema fully covers parameters (100% coverage with none present), and the description adds value by naming the output fields rather than parameter details.

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

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

The description uses a specific verb ('List') with a clear resource ('all MLB teams') and names the data source ('official MLB Stats API'). It also enumerates the returned fields, so an agent can distinguish it from sibling tools like mlb_roster or mlb_schedule without opening schemas.

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

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

The description makes the use case clear: when an agent needs a complete list of MLB teams with identifiers and basic metadata, this is the tool. It does not explicitly name alternatives or state when not to use it, but the direct task framing provides enough context for correct selection.

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

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

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 goes well beyond the annotations by disclosing matching mechanics, safety codes, fee treatment, null semantics, and caveats like 'pairing_unverified' and 'every spread_pp is gross, not a net tradeable edge.' It explicitly explains what could be misinterpreted, such as temporal_alignment null meaning 'could not be computed, not aligned.' Annotations are readOnly/idempotent/non-destructive and the description does not contradict 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 it is densely informational and organized with clear section markers like TWO MODES, RESPONSE, and SAFETY FIELDS. It front-loads the core purpose before enumerating codes and edge cases. Some redundancy exists (e.g., temporal_alignment_unknown is explained in multiple places), but there is no filler and the length is justified by tool complexity.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it delivers: raw probabilities, top_spreads_pp, compatibility_warning/codes, per-entry flags, skipped counters, low_confidence_pairs, temporal_alignment, and fees_note are all described. It also handles failure/edge states such as no matching pairs, unknown metric types, and unparsed resolution months. The agent is equipped to interpret results without additional documentation.

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

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

Schema coverage is 100%, so each parameter already carries a description. The tool description adds meaningful semantics by enumerating all 10 topic values, explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and clarifying that both modes run the same matcher. This goes a step beyond the schema alone.

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 opens with a specific, unambiguous statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then identifies two concrete modes (topic shortcuts and explicit ticker/slug pairings), which fully distinguishes the tool's operation. This is a clear verb+resource+scope statement that differentiates it from sibling analysis 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 explains when to use the topic shortcuts versus the explicit pairing mode, and warns that pre-mapped topics are not automatically tradeable. It does not name alternative sibling tools such as polymarket_arbitrage or polymarket_edges, so there is no direct exclusion guidance. However, the operational context within the tool is clear and practical.

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?

Annotations already mark it read-only, open-world, and idempotent, and the description adds substantial behavioral detail beyond that: ambiguous names return figi_candidates rather than asserting false results, unresolved identifiers are listed under unresolved instead of omitted, sources are labeled per identifier, and LEI/FIGI enrichment degrades gracefully when external services are unavailable. No contradiction with annotations exists.

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

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

The description is front-loaded with purpose and common queries, and most sentences carry useful information. It is quite long and dense, with heavy parentheticals that make scanning more effortful, but the complexity of the tool justifies much of 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?

For a two-parameter tool with no output schema, the description covers input forms, resolution behavior, output fields, ambiguity handling, source labeling, unresolved results, and fallback behavior. An agent has enough context to call the tool correctly and interpret its responses in most cases.

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

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

Schema coverage is 100%, but the description adds critical semantics beyond the schema. It specifies accepted company inputs including ISIN, explains the ISIN-to-LEI resolution path, and gives a crucial usage warning for the value parameter: pass only the entity name as printed, never the full noun phrase, because trailing security-class words will fail FIGI matching.

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: resolving user-spoken names to canonical/official identifiers, with concrete query examples. It also names the two supported entity types and distinctly frames the tool as the identity-lookup step before other tools, separating it from siblings like entity_profile and compare_entities.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also notes that a single call replaces 2–3 manual lookups, which helps the agent decide when to invoke it. However, it does not explicitly state when not to use it or name alternatives for deeper entity investigation.

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.