Balldontlie

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

Annotations declare readOnly, idempotent, openWorld hints. The description adds context about cost (free default vs BYO key for Anthropic), per-model return structure (score, confidence, signals, raw_response), and combined view. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the core action, then adding key details (default model, BYO key, return format). Every sentence serves a purpose with no redundancy.

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

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

No output schema exists, but the description compensates by detailing the per-model and combined return structure. It covers all key behaviors (cost model, key requirement, return fields). Minor gaps (e.g., rate limits, pagination) are acceptable for this complexity.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining the default model, key integration (BYO key for Anthropic), and the return format beyond the schema. This context helps agents understand parameter semantics better.

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 entity knowledge and scores visibility (0-100) per model. It specifies supported models, default, and return format. This distinguishes it from sibling tools like entity_profile or compare_entities, which focus on structured entity data or direct comparison.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), guiding when to use. However, it doesn't explicitly call out alternatives or when not to use, missing some differentiation from related tools.

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

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

Annotations already flag readOnly/openWorld/idempotent/destructive hints, and the description adds behavioral context beyond these: it routes across 5,529 tools from 1,455 sources, returns structured answers with stable pipeworx:// citation URIs, and claims 'one fast call' performance. This enhances the agent's expectation of response format and scope without conflicting with the annotations.

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

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

The description is longer than average but earns its length through structured, front-loaded guidance. It starts with the key preference directive, then covers domains, examples, and alternatives in a logically ordered paragraph with dash-separated examples. Every sentence serves a purpose, though minor trimming could tighten the list of trigger phrases.

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 (a general router over 5,529 tools, 1,455 sources) and the absence of an output schema, the description is remarkably complete. It specifies scope, return format (structured answer with citation URIs), triggers, and escalation pathways to sibling tools. No critical behavioral or operational detail is missing for an agent to select and invoke it correctly.

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

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

Input schema covers all 6 parameters with 100% description coverage, including aliases; the question field is self-explanatory. The tool description only indirectly references the question parameter through examples and does not add new semantic details beyond the schema. Therefore a baseline score of 3 is appropriate since the schema carries the parameter burden.

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 precise directive ('PREFER OVER WEB SEARCH for questions about current or historical data') and enumerates supported domains, making the tool's scope explicit. It also distinguishes itself from sibling tools ask_pipeworx_grounded and deep_research by naming when each is appropriate. The verb 'ask' plus the routing behavior clearly defines it as a natural-language question-answering gateway.

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

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

Usage guidance is explicit and actionable: 'START HERE for most questions' declares it the default entry point, and 'step up only when needed' names specific alternatives with their use cases (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). Trigger phrases and concrete examples ('current US unemployment rate', 'Apple's latest 10-K') leave no doubt about when to invoke.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds crucial context: the beta status, that routing improvements may be enabled live, that no candidate is currently active, and that it is a full working router (not a fallback). This fully discloses the experimental behavior without contradicting annotations.

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

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

The description is front-loaded with the core identity in the first sentence, followed by current status and usage guidance. Every sentence adds value, with no fluff or repetition. It is appropriately concise for the information conveyed.

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

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

Given the tool's simplicity (a router with a single required parameter) and the rich annotations and schema, the description fully covers what an agent needs: what it does, current state, usage recommendation, and reassurance that it works fully. No output schema is needed since it matches ask_pipeworx's response shape.

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

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

The input schema covers 100% of parameters with clear descriptions (question and its aliases), so the schema does the heavy lifting. The description only notes 'same arguments' as ask_pipeworx, which adds no specific detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental nature, making the purpose specific and well-defined.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also provides context that results are compared against the stable router, and notes the current state (no active candidate) makes it identical to ask_pipeworx. This gives clear guidance versus the sibling 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?

Discloses key behavioral traits beyond annotations: return format with evidence and confidence, explicit refusal reasons, extra LLM call cost, and that answers are extracted only from tool results. This aligns with but significantly extends the readOnly/openWorld/idempotent hints, giving the agent a full model of 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 information-dense but every sentence earns its place: definition, mechanism, return schema, refusal modes, usage guidance, and cost trade-off. No redundancy or filler; structured to transfer maximum understanding quickly.

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

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

Despite lacking an output schema, the description fully specifies return success and failure structures, refusal reasons, cost implications, and use cases. It is complete for a tool of this complexity, covering gaps that would otherwise require guessing.

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

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

Schema coverage is 100% and the single meaningful parameter (question) is self-explanatory with aliases documented. The description adds no parameter-specific detail because none is needed; baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, with a specific verb (extract grounded answers) and resource (Pipeworx tool routing). It explicitly distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior.

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

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

Provides explicit usage guidance: use when answers will be quoted/cited/acted on, and prefer ask_pipeworx for casual lookups due to extra cost. Names the alternative and gives a clear decision rule, going beyond mere context to exclusionary guidance.

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

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

The description goes far beyond the annotations (which already indicate read-only, idempotent, non-destructive behavior) by detailing resolution logic, fan-out patterns, response shapes, error behaviors (low-confidence short-circuit, closed markets), risk features (spread warning, cancellation rule), and specific data handling (news fallback, raw vs summarized output). This is exceptionally transparent.

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

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

The description is very long (multiple paragraphs) and densely packed with information. While every sentence adds value, the length could be reduced for quicker consumption. The structure is logical (purpose, usage, response, safety), but front-loading the most critical constraints (e.g., matching confidence short-circuit) would improve usability.

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 (3 parameters, no output schema, many sibling tools), the description is remarkably complete. It covers inputs, behavior, output structure, error handling, edge cases (closed markets, wide spreads), resolution risks, and even ties to cache/performance. No gaps are apparent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the accepted formats for the 'market' parameter (slug, URL, question text), the effect of 'depth' (quick vs thorough evidence count), and the trade-off of 'include_raw' (response size vs completeness). This context meaningfully supplements the schema.

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

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

The description begins with a clear verb-resource-action statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by being a comprehensive research tool that resolves markets, classifies bets, and fans out to multiple data sources.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description includes numerous examples (BTC bet, Fed bet, etc.) that illustrate when the tool is appropriate. However, it does not explicitly state when not to use it or mention alternative tools for specific sub-tasks.

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?

Details data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint).

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?

Relatively dense but well-structured with trigger phrases, type-specific details, and return format. Every sentence adds value, though slightly longer than minimal.

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 2 required parameters and clear purpose, the description covers usage triggers, data sources, sorting, return format (paired data + URIs), and efficiency benefit (replaces 8-15 lookups). No output schema needed.

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

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

Schema coverage is 100% with parameter descriptions. The description adds contextual examples (tickers, drug names) and constraints (max 5, min 2), going beyond basic schema info.

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?

Explicitly states side-by-side comparison of 2-5 companies or drugs with trigger phrases. Distinguishes from siblings like entity_profile (single entity) and search tools.

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

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

Provides clear trigger phrases ('compare X and Y', 'which is bigger') and explicitly advises to prefer over sequential single-entity lookups. Differentiates when to use company vs drug type.

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 state readOnly/openWorld/idempotent/non-destructive. The description enriches this with account/auth requirements, paid tier for 'thorough', explicit statement that it never invents answers, gaps[] and contradictions[] behavior, semantic excerpting, citation resolvability via pipeworx:// URIs, and latency expectations (15-90s). 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?

Although long, every sentence contributes critical operational context: account requirements, tool scope, alternatives, output packet structure, behavioral nuance (gaps, contradictions, citation resolvability), and latency. The description is front-loaded with the most urgent access constraint and then flows logically, with no redundant filler.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It covers prerequisites (account, paid tier), what to expect in the response (findings packet, gaps[], contradictions[], hop fields, citation_uri), failure modes (empty gaps for off-catalog topics), and performance (15-90s). This fully equips an agent to decide whether and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by clarifying that the question parameter accepts broad, multi-part natural language ('decomposition is the point') and by reiterating depth semantics in context, including the paid tier caveat for 'thorough'. This goes slightly beyond redundant schema restatement.

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

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

The description uses a specific verb+resource ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources') and clearly distinguishes from siblings by emphasizing it is NOT open-web search and involves decomposition into facets routed in parallel to 5,529 tools. It also names the main alternative (ask_pipeworx) and specifies when each is appropriate.

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 provided: single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx because deep_research will return empty gaps[], and unsigned-in users should use ask_pipeworx. This is strong when-to-use vs. when-not-to-use guidance directly tied to sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds context about output: returns names, descriptions, full input schemas with curated examples, and that results are ready to call. No contradictions. Adds 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?

Description is about 5 sentences, front-loaded with purpose, then usage, then return value. Every sentence adds value and is well-structured. No fluff.

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

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

Given no output schema, the description explains the return value comprehensively (names, descriptions, full input schemas with examples) and notes it's ready to call. Also provides context on when to use. With 6 parameters fully documented, it is complete.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'natural language description' and lists aliases, which mirrors the schema. No additional semantic detail beyond what is in the schema.

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

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

The description clearly states the tool finds/discover tools based on a data or task description. It specifies the verb 'find' and resource 'tools', and provides concrete examples. It distinguishes itself from sibling tools by focusing on tool discovery rather than direct analysis 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?

Explicitly states when to use: 'Call this FIRST when you have many tools available and want to see the option set'. Gives examples of domains. Could be more explicit about when not to use (e.g., if you already know the tool), but the guidance 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: fans out across multiple sources, returns specific fields, notes patents soft-fail due to USPTO sunset, and explains fallback mechanisms (GDELT→GNews). No contradictions.

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

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

The description is front-loaded with example queries, then structured with bullet points listing data sources and return fields. Every sentence adds value; no waste. Appropriately sized for 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 lacking an output schema, the description thoroughly enumerates all returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details on limitations (up to 5 filings, latest 10-K, patent soft-fail). Covers all information an agent needs to understand the tool's 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 descriptions already cover both parameters: type (enum) and value (ticker or CIK, names unsupported). The description adds examples (AAPL, CIK format) but does not provide substantial new meaning beyond the schema. With 100% schema coverage, 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 returns a full cross-source profile of a US public company, using specific verbs like 'profile', 'brief', 'research'. It distinguishes itself from siblings by explicitly instructing to use this tool over chaining single-pack lookups for holistic views.

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: when user asks for a holistic view ('Tell me about X', etc.). Also gives when-not-to-use: names are not supported, so use resolve_entity first. This provides clear context and alternatives.

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

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

The description's 'Delete' action aligns with the destructiveHint annotation, but it does not add significant behavioral context beyond what annotations already provide. The idempotentHint is not mentioned, and there is no disclosure about what happens if the key does not exist.

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 consists of two short, front-loaded sentences with no unnecessary words. Every part serves a purpose: stating the action, providing usage context, and suggesting related tools.

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

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

Given the tool's simplicity (1 required param, no output schema, annotations present), the description adequately covers the core action and usage guidance. It could mention the idempotent nature or return behavior, but overall it is sufficient for selecting and invoking the tool.

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

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

Schema coverage is 100% for the single 'key' parameter. The description's 'Memory key to delete' is essentially identical to the schema description, adding no new meaning beyond the structured data.

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 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It distinguishes itself from siblings like 'remember' and 'recall' by mentioning them in the usage guidelines.

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

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

The description explicitly says when to use this tool ('when context is stale, the task is done, or you want to clear sensitive data') and suggests pairing with 'remember' and 'recall'. However, it does not provide explicit when-not-to-use or alternative tools beyond the pair.

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 the specific output fields (matchup, scores, etc.), but given the output schema exists, the added value is moderate.

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?

A single, concise sentence that front-loads the tool's purpose and usage guidance, with no redundant 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 the tool's simplicity (one parameter), rich annotations, and existing output schema, the description fully covers what the agent needs to know for correct invocation.

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

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

The description adds meaning by stating the tool works 'by ID', clarifying that the single parameter is a game identifier. With 0% schema coverage, this compensation is sufficient for a simple number 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 it retrieves a single NBA game by ID, listing specific data fields (matchup, scores, date, etc.), which distinguishes it from the sibling tool 'games' that lists multiple games.

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

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

Explicitly advises to use this tool after 'games()' to fetch detail, providing a clear workflow and contrasting with the listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds return fields but no additional behavioral details like pagination behavior or rate limits. With comprehensive annotations, the bar is lower, and the description provides adequate but not extra 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?

Two sentences: first states functionality and output, second gives use cases. No superfluous words. Information is front-loaded and clearly structured.

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

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

Given the rich annotations and existence of an output schema, the description covers the essential purpose and typical use cases. Missing details about pagination or ordering are minor omissions; overall it is sufficiently complete for a read-only data retrieval tool.

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

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

Schema description coverage is 17% (only 'dates' described). The description mentions filtering by season, team, or date range, which helps for three parameters (seasons, team_ids, dates). However, cursor, per_page, and postseason are not explained. This partially compensates for low coverage but leaves gaps.

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 specifies the tool is for NBA games filtered by season, team, or date range, and lists what fields are returned. It provides concrete use cases like 'did the Lakers win last night' and distinguishes from sibling tools like 'game' (singular) through plural naming and scope.

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

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

The description explicitly states when to use the tool (schedule lookup, historical game search) but does not mention when not to use it or compare with alternatives like the singular 'game' tool. The use cases are clear, but explicit exclusions are missing.

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 the tool safe (readOnly, idempotent). The description adds the internal process: fetch page, extract title/description/links, emit markdown. This enriches understanding without contradicting annotations.

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

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

Two sentences: first covers purpose and audience, second covers process and output. Every word adds value; no filler. Front-loaded with the key verb 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?

Given no output schema, the description explains the output format ('single text blob') and its intended use ('drop at site-root/llms.txt'). Combined with annotations, it provides a complete picture for a simple 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%; both 'url' and 'max_links' are described in the schema. The description does not add new semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly specifies the action ('Generate'), the resource ('llms.txt file'), and the target audience ('AI crawlers'). It distinguishes itself from siblings like 'ai_visibility_check' by focusing on file generation rather than visibility analysis.

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

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

Explicitly lists three concrete use cases (client indexing, personal project drafting, competitor auditing), providing strong usage context. However, it does not mention alternatives or when not to use, which would have made it 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 the tool read-only, non-destructive, and idempotent. The description adds return format context but no additional behavioral disclosure beyond annotations.

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

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

Two sentences: first states purpose and return format, second gives usage guidance. No wasted words, front-loaded.

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

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

Given a single optional parameter and no output schema, the description adequately covers what the tool does, returns, and when to use it. It is sufficiently complete for a simple list tool.

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

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

Schema coverage is 100%, with the parameter include_inactive fully described. The description does not add any extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb (list), resource (subscriptions), and scope (caller's active). It also lists the return fields, distinguishing it from siblings like subscribe and unsubscribe.

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

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

The description provides clear context on when to use this tool: to review current subscriptions before adding more or to find an id for cancellation. It implicitly guides not to use for subscribing/unsubscribing.

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

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

Annotations are all false, but the description adds substantial behavioral context: rate-limited to 5 per identifier per day, free (doesn't count against quota), returns a claim_token when filed without an account, and how to use that token to check status. It also clearly states that reports are read daily and influence the roadmap. This goes far beyond the annotations.

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

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

The description is a single dense paragraph, but every sentence carries meaningful information. It could be more scannable with bullets or separation, but no content is redundant. The front-loaded purpose makes it easy to understand immediately.

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 4 parameters, nested context, and no output schema, the description fully covers all necessary aspects: when to use, specific field guidance, token handling, rate limits, and expectations. Nothing is left unexplained that an agent would need to invoke this 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 descriptions cover all parameters (100%), so baseline is 3. The description adds extra value by explaining the claim_token usage pattern (pass it with no other arguments to read the reply) and by warning not to paste the end-user's prompt. This additional guidance raises the score above baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This distinguishes it from siblings since no other tool provides feedback to the Pipeworx team. The verb 'tell' and specific resource make the action unambiguous.

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

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

Explicit guidance is provided for when to use the tool (bug, feature, data_gap, praise) and when not to use it (tools from a different MCP server). It also explains the claim_token workflow for following up on reports, giving complete context on 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 mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context: it's self-aggregating from CF analytics, no PII, and cached for 5min-1h. This helps the agent understand data freshness and privacy. 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?

Extremely concise: three short paragraphs that front-load the main output and purpose, followed by use cases and caveats. Every sentence is informative and earns its place. 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, the description adequately explains the return structure (tools, packs, volume). It mentions caching behavior. It could briefly mention pagination or limit, but for a trending endpoint, this is 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 covers the single parameter 'window' with enum and description, achieving 100% coverage. The description adds semantic guidance: 'Shorter windows surface what is hot right now; longer windows show steady-state demand,' which supplements the enum values.

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 returns 'top tools, top packs, and total call volume' over configurable windows. The verb 'Returns' is specific, and the resource is well-defined. It distinguishes from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregate usage data.

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?

Three explicit use cases are listed, providing clear context for when to use. However, it does not explicitly state when not to use or name alternatives directly. The context is strong enough for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds context about the expected output fields and usage order, which is useful but not contradictory to 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, well-structured sentence that concisely conveys the tool's purpose, output fields, and usage hint. No wasted words.

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

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

Given the simple input (one numeric ID), the presence of an output schema, and clear annotations, the description is complete. It tells the agent what to expect and how to use the tool effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'by ID' but does not explain the parameter's meaning, type, or constraints beyond that. The example in the schema (id: 237) helps but is not part of the description.

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

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

The description clearly states the tool retrieves a single NBA player by ID and lists the fields returned (name, position, height, weight, jersey, team). It distinguishes from the sibling 'players' tool by specifying singular retrieval.

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 to use this tool after 'players()' to confirm details, providing clear usage context. However, it does not state when not to use it or mention 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 declare readOnlyHint=true and destructiveHint=false, making the safety profile clear. The description adds no behavioral traits beyond these annotations, but lists return fields, which is moderately useful. 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?

Two concise sentences with no unnecessary words. The purpose is front-loaded and every part 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?

The description covers the core functionality and use case (ID resolution). Pagination parameters (cursor, per_page) are not explained, but an output schema exists. Overall, the description is sufficiently complete for the tool's moderate complexity.

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

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

The description explains the purpose of 'query' (name substring) and 'team_ids' (filter by team), but does not describe 'cursor' or 'per_page'. Schema coverage is only 25%, so the description partially compensates but leaves gaps.

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 is an NBA player roster, supports search by name substring or filter by team, and lists return fields. It distinguishes itself from the sibling tool 'player' by specifying it resolves names to numeric IDs needed by 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?

The description explicitly states 'Use to resolve a player name to a numeric player_id required by stats/season_averages,' providing clear usage guidance. It does not explicitly state when not to use, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint. Description adds rich behavioral context: monotonicity checks, partition sum, semantic anchor, partition filter, fill check with book depth analysis. Clearly states the tool does not execute trades, only signals.

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?

While verbose, the description is front-loaded with purpose and mode guidance. Some redundancy (e.g., repeated mention of partition_check details) but justified by tool complexity. Could benefit from bullet points or clearer paragraph separation.

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 thoroughly explains the response structure (opportunities[] fields, partition_check details, fill_check output). Covers all aspects needed for agent to understand usage and results.

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 brief descriptions. The tool description greatly expands meaning: explains event slugs, topic queries, and detailed behavior for each mode, far exceeding basic schema info.

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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

Explicitly instructs when to use each mode: 'Call with NO args for a trending_scan...', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. Also provides critical guidance on fill check and when not to trade.

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 extensively details behavioral traits: model families, edge calculation (edge_pp_net after slippage, Kelly fractions), caching (1h at KV level), diagnostics for empty segments, and Fed market caveats. This far exceeds what annotations (readOnly, idempotent, openWorld) 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 lengthy but well-structured: purpose, model families, response format, knobs, diagnostic info. Every section earns its place given the tool's complexity. Minor redundancy (e.g., repeating 'opportunities' multiple times) prevents a perfect score.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and edge cases (e.g., why segments might be empty, caching behavior). For a complex tool with 9 parameters, this completeness is exemplary.

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 thorough parameter descriptions. The tool description adds extra context on 'tradeable-edge knobs' (min_liquidity, max_spread_pp) and explains subtle behaviors like min_partition_leg_kelly applying to per-leg Kelly inside partitions, going beyond the schema's documentation.

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 positions it for daily discovery ('what should I bet on today'), distinguishing it from generic market scanners.

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

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

The description provides strong usage context ('agents discover opportunities without paging hundreds of markets') but lacks explicit guidance on when not to use or how it differs from siblings like 'polymarket_arbitrage' or 'polymarket_edge_tracker'.

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, non-destructive), the description adds behavioral details: response structure (tracked[], expired[], snapshot_dates[]), computed fields (trend, decay_pp_per_day), and limitations (60-day TTL, decay from daily closes, gaps in snapshots). This enriches the agent's understanding.

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 front-loads the purpose but is overly verbose, especially in the response structure section. While well-organized with clear sections, it could be more concise to improve readability for an AI agent.

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 thoroughly explains the response fields and their meanings, including edge_pp_net time-series, trend, decay, expired lifespan, and snapshot dates. Limitations are acknowledged, making it fairly complete for the tool's complexity.

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

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

Both parameters have descriptions in the input schema (100% coverage). The description adds default values and max for 'days' (max 30, clamp 2-30) and briefly restates window options. This provides some additional context but does not significantly surpass what the schema already conveys.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering how long edges exist and if they are shrinking. It specifies the output includes tracked opportunities with time-series, trends, and expired items, distinguishing it from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

The description implies usage for checking edge longevity but does not explicitly state when to use this tool over alternatives (e.g., polymarket_edges for current edges). No exclusions or comparisons are provided, leaving the agent to infer context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant context: ladder walking, verdict options, thin legs, forced directional risk, and the warning that partial basket fills convert an arb into an unhedged directional position. It thoroughly discloses behavioral traits 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 well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded with the core purpose. Every sentence adds value, and while detailed, it is concise for the complexity of the tool. No waste.

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

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

Given the complexity (two modes, multiple return fields), no output schema exists, but the description comprehensively details all return values for both modes, including edge cases (thin_legs, forced_directional_risk). It provides sufficient context for an agent to use the tool correctly without needing additional information.

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 description adds meaning to parameters: explains single-market vs. basket modes, auto-detection of side in basket mode, interpretation of size_usd (max spend on buys, target proceeds on sells). Goes beyond schema definitions to clarify usage 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 a realizable-vs-theoretical edge check against live CLOB depth, distinguishes between single-market and basket modes, and lists specific return values. It effectively differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says when to use the tool ('before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'), provides rationale for why it's needed, and implies when not to use (small trades). Gives clear context for agent decision-making.

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

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

The description adds significant behavioral context beyond the annotations: it details compatibility_warning, temporal_alignment, skipped comparison counters, and conditions that render spreads meaningless (e.g., non-equivalent bet shapes, temporal mismatch). No contradiction with annotations.

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

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

The description is lengthy but well-structured with sections for MODES, RESPONSE, and SAFETY FIELDS. Every sentence adds value, though it could be slightly more concise without losing critical 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?

Given no output schema, the description thoroughly covers return fields (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skipped counters). It addresses all likely agent questions about the behavior and interpretation of results.

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 value by explaining the topic enum values (10 shortcuts) and their auto-mapping behavior, and how explicit parameters override topic. It also describes the interaction between parameters (modes). Baseline 3 for high coverage, but the 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 identifies the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('compute', 'auto-fetch') and distinctively sets itself apart from siblings like polymarket_arbitrage by being explicitly cross-venue.

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 explains two modes (topic shortcuts vs explicit tickers) and their appropriate usage. It also warns about compatibility_warning scenarios where spreads are meaningless, and notes that real spreads are rarer than the shortcut list suggests, guiding the agent on when not to use the 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds scoping details and pairing instructions. 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?

Two concise sentences, front-loaded with the main action. Every sentence adds value: retrieval behavior, usage context, and relationship to sibling tools.

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 simple tool with good annotations and schema, description covers purpose, usage, and behavioral context adequately. Absence of output schema is acceptable for a retrieval tool.

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

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

Schema coverage is 100% with description for the single parameter. Description adds the important behavior that omitting key lists all keys, which is not in schema examples.

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 retrieves a value by key or lists all keys. It distinguishes itself from sibling tools 'remember' and 'forget' by focusing on retrieval, and uses specific verb 'retrieve' and resource 'value previously saved'.

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 use case: look up stored context without re-deriving. Describes scoping (identifier-based) and pairs with remember/forget. Lacks explicit when-not-to-use, but context is clear enough.

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

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

The description contradicts the readOnlyHint=true annotation by stating that mark_read:true 'flag returned events read so the next call only shows newer ones,' which implies a state mutation. This is a clear annotation 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?

Front-loaded with purpose, then efficiently covers parameters and usage in a compact paragraph. A few words could be trimmed, but overall well-structured and focused.

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 explains return content (source, citation_uri, payload) and all parameters. Also provides context for polling and an alternate access method, making it complete for a read-oriented polling tool.

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

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

Schema coverage is 100% (baseline 3). The description adds concrete examples ('e.g. sec_8k'), clarifies the ISO format for since, and explains the effect of mark_read on subsequent calls, providing meaning beyond the schema.

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

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

The description opens with a clear, specific verb+resource: 'Pull fired events from your subscription feed.' It enumerates what each event carries (source, citation_uri, raw payload) and distinguishes itself from sibling tools like list_subscriptions by focusing on returned alert events.

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 good usage guidance: explains filtering by type and since, the mark_read parameter for read state, and notes that polling works. Mentions an alternative REST endpoint for scripts, though does not explicitly contrast with sibling tools like ask_pipeworx.

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, destructiveHint, and openWorldHint. The description adds valuable behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains the fallback logic, and notes the PatentsView API sunset. No contradiction with annotations, but could mention rate limits or response size.

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 fairly long but well-structured: example queries first, then tool behavior, then parameter details, then return format. It avoids tautology and earns its sentences, though some phrases like 'in ONE parallel call' could be omitted without loss.

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 clearly states the return format ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It covers fallback behavior, parameter usage, and a sibling reference. For a 3-parameter tool with moderate complexity, this is complete and 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%, yet the description goes beyond: for 'since' it clarifies ISO and relative formats with examples, for 'type' it confirms only 'company' is supported, and for 'value' it explains ticker or CIK input. This adds significant meaning 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 opens with concrete user query examples ('What's new with X', 'latest on Y') and clearly states the verb+resource: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the data sources and distinguishes itself from sibling entity_profile.

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

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

The description explicitly advises 'Use entity_profile instead when you want the static profile', providing an alternative for a different use case. It also gives a best-practice recommendation for the 'since' parameter ('Use "30d" or "1m" for typical monitoring'). However, it lacks explicit 'when not to use' guidance beyond the one sibling reference.

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 idempotent and non-destructive writes. Description adds valuable context: key-value storage, persistent vs. 24-hour retention based on authentication, and scoping. 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?

Four concise sentences, front-loaded with purpose, quickly covering usage, scope, retention, and companion tools. 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 the simplicity of a write-only tool with no output schema, the description fully covers purpose, usage, behavior, and lifecycle. 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?

Input schema already provides descriptions for both parameters (key and value) with examples. Description adds context on expected usage patterns but the schema covers the meaning fully.

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

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

Clearly states the tool saves data for reuse across sessions, with specific examples (resolved ticker, target address, user preference). Distinguishes from sibling tools recall and forget, which are mentioned as partners.

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

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

Explicitly tells when to use: when discovering something worth carrying forward. Provides pairing guidance with recall and forget, and mentions scoping by identifier. No ambiguity.

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

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

Annotations already establish it as read-only, idempotent, and non-destructive. The description adds valuable behavioral details beyond annotations: graceful degradation when GLEIF/OpenFIGI are unavailable, explicit reporting of unresolved identifiers, and the internal cascade through multiple lookup endpoints. This gives the agent a clear operational model.

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

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

The description is longer than average but each sentence earns its place — it includes examples, supported types, return components, and failure behavior. It is front-loaded with typical user queries, making it immediately recognizable. Slightly verbose but not redundant; a well-structured block.

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

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

For a tool with no output schema, the description thoroughly covers expected returns per type: company returns CIK, ticker, company_name, LEI, ownership hierarchy, FIGI; drug returns RxCUI, ingredient, brand, and a citation link. It also explains fallback behavior for enrichment sources. Given the tool's complexity, this is complete enough for an agent to anticipate results.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description enhances parameter understanding by explaining the 'type' enum in detail (company vs drug) and adding examples for the 'value' parameter (AAPL, CIK, 'ozempic'). It clarifies that 'value' accepts name, ticker, or CIK for company, which is consistent with the schema but with more context.

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

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

The description opens with concrete example queries that define exactly when the tool is needed: resolving a spoken name to canonical identifiers. It clearly states the tool's function — 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' — and distinguishes it from siblings by positioning it as the first step for ID lookup.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives example phrasings and supported entity types. While it doesn't explicitly say when *not* to use it or mention alternative tools, the 'Use FIRST' directive implies priority. This is clear context without 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 readOnly, idempotent, openWorld, non-destructive. Description adds procedural details (probes, ranks, treats first entity as subject) and mentions API key requirement for certain models. 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, then method, then example use case. No extraneous words. 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?

While output schema is absent, description specifies return includes rank, score, confidence, signal density per entity. This is sufficient for most agents, though explicit field names or structure would improve completeness.

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 3. Description adds contextual meaning: entities array size 2-8, first is subject, rest competitors; models and _apiKey explained relative to workflow. Slight extra value beyond schema.

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

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

Clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks results, and identifies most/least recognized. Differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Explicitly positions tool for competitive AI-marketing audits and contrasts with single-entity use case via ai_visibility_check. The 'when-not' is implied; providing an explicit alternative would be stronger, but the description effectively guides 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 already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30 seconds, and the `sources_failed` field will list timeouts. This goes beyond the structured annotations.

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

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

The description is relatively lengthy but every sentence provides necessary information: purpose, what it fans out, return shape, limitations, and failure behavior. It is front-loaded with the main purpose. Could be slightly tighter, but overall well-structured for the information density.

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

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

Given the tool has two parameters, no output schema, and modest complexity, the description covers all important aspects: what it does, what it returns (summary block, advisories, links, alternatives), error handling, timing behavior, ecosystem limitations, and feature set. No gaps identified.

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 does not add extra parameter semantics beyond what the schema already provides (package name and version). It mentions the parameters in context but no additional constraints or formatting rules.

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 composite check for npm packages combining deps.dev and bundlephobia, and specifically mentions the use case of answering 'is X safe / popular / small' or 'what does adding lodash cost me'. It distinguishes from other ecosystems by explicitly stating NPM-only in v1 and directing to deps.dev for others.

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 whenever an agent asks...' and also clarifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and when-not-to-use guidance, differentiating from sibling tools.

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

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

Adds substantial value beyond annotations: details embedding model (BGE-base-en), similarity measure (cosine), chunking strategy (500-char overlapping windows), input cap (200K chars), truncation behavior, and offset for verification. Annotations only cover read-only, idempotent, non-destructive hints.

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

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

Well-structured with front-loaded purpose and usage, followed by behavioral details. Each sentence adds value, though slightly lengthy. Could be trimmed slightly without losing substance.

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 (top-N passages with offsets and scores) and mentions truncation flag. Covers essential behavioral aspects for agent decision-making, though could explicitly mention return types.

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 schema already documents parameters. Description adds context like max chars for text, default and range for limit, and natural-language examples for query, providing meaningful elaboration 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 'semantic search INSIDE a fetched record' with specific verb+resource. Distinguishes itself by mentioning return of character offsets and pairing with ask_pipeworx_grounded, setting it apart from 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 when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, providing clear usage context. Does not explicitly list when not to use, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns specific stat averages but does not discuss data freshness, pagination, or any side effects. Given rich annotations, the description provides marginal extra transparency.

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

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

The description is a single sentence that is front-loaded with the action ('Fetch') and includes essential details (resource, parameters, output). No unnecessary words 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?

The description covers inputs (player_ids, season) and outputs (PTS, REB, AST, FG%, other averages). It lacks mention of whether data includes playoffs or regular season, and does not reference the existing output schema. Overall, it is sufficiently complete for a straightforward data retrieval 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 0% (no parameter descriptions), but the description mentions 'one or more player_ids in a given season year', clarifying both season and player_ids parameters. However, it does not specify data types or constraints (e.g., season format, player_id range), so it adds moderate meaning but not full clarity.

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

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

Description clearly states the verb 'Fetch' and resource 'per-season NBA stat averages' for specific player_ids in a given season year. It lists return fields (PTS, REB, AST, FG%) which distinguishes it from sibling tools like 'player' or 'stats' that likely provide different data.

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

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

The description implies the tool is for retrieving per-season averages for identified players, but it does not explicitly state when to use it instead of alternatives (e.g., 'player', 'stats', 'games'). No exclusions or prerequisites are provided.

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 value by listing the returned stats (PTS, REB, AST, etc.) and filter options, but does not elaborate on pagination behavior (cursor parameter), error scenarios, or rate limits. With annotations covering safety and idempotency, the description provides moderate additional context.

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

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

The description is two sentences, front-loaded with the core action and return data, with no filler or redundancy. Every sentence contributes essential information.

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

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

Despite low schema coverage (0%), the description does not fully explain all parameters (e.g., cursor, per_page, postseason) or pagination. While output schema exists, the description should compensate for missing parameter documentation to ensure the agent can invoke the tool correctly. Current depth is insufficient for a tool with 6 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 description coverage is 0%, so the description must compensate. It mentions filtering by 'player, team, game, or season', but the schema includes 'team' only implicitly (no parameter named 'team'), and lacks explanation for 'cursor', 'per_page', and 'postseason'. Only 3 of 6 parameters are partially described, leaving significant ambiguity for the agent.

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 providing per-game NBA player box-score stats with specific metrics (PTS, REB, AST, etc.) and filtering dimensions (player, team, game, season). This distinguishes it from sibling tools like 'player' or 'season_averages' by focusing on individual game performance.

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

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

The description states explicit use cases ('individual game performance lookup, box-score analysis, fantasy stats'), providing clear context. However, it does not specify when to avoid this tool or mention alternatives like 'player' (for player info) or 'season_averages' (for season-level data), which would strengthen 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?

Discloses authentication requirements, delivery limits (10/day SMS), and webhook secret one-time return. Annotations indicate idempotentHint=true, but description does not explicitly confirm idempotency, though it's implied.

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?

Information-dense yet well-organized: purpose first, then requirements, then type-specific details, then delivery channels. No redundant sentences.

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

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

Covers authentication, all 5 subscription types with parameter examples, delivery channels with limitations, and webhook signing details. No gaps given complexity.

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

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

Schema coverage is 100%, but description adds substantial value with detailed examples for each type, parameter syntax, and delivery constraints, far exceeding baseline.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and lists supported types, 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?

Explicitly notes the requirement for a Pipeworx OAuth account, provides examples for each subscription type, and mentions delivery channel options. Could add explicit when-not-to-use guidance.

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

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

Annotations already declare safe read-only, idempotent behavior. Description adds that the tool returns organized examples from a live catalog and covers the output nature without contradiction. Some detail on output structure missing but adequate given lack of 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?

Description is well-structured and front-loaded with trigger phrases, but slightly long. Every sentence adds value, balancing completeness with efficiency.

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 onboarding purpose, the description fully covers what it does, how to use it, and when to use it. No output schema, but the description compensates with sufficient behavioral detail.

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

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

Schema coverage is 100%, and description adds semantic context by listing valid topic values and explaining the effect of omitting the parameter, 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 returns category-bucketed example questions with exact tool and argument shapes. It lists multiple trigger phrases and distinguishes the tool from sibling meta-tools like ask_pipeworx and discover_tools.

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

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

Explicit guidance to use this tool first when onboarding, with examples of when to pass topic vs omit. Does not explicitly state when not to use it, but the positive usage context is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field names but no extra behavioral context. With annotations, bar is lower, but description adds minimal new behavioral info.

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: one sentence specifying action and fields, plus a usage hint. No wasted words.

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

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

For a simple single-parameter tool with an output schema, the description is complete. It covers purpose, fields, and usage context.

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

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

Schema has 0% description coverage for the single parameter 'id' (number). Description does not elaborate on what the id represents beyond 'by ID'. Minimal added semantic value.

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

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

Description clearly states it retrieves a single NBA team by ID, listing fields (name, abbreviation, city, conference, division). This distinguishes it from sibling 'teams' which likely lists 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?

Explicitly suggests using after teams() to confirm details, providing a clear usage scenario. Does not explicitly exclude alternatives but gives good context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it returns all 30 teams and specific fields, which is consistent but does not disclose additional behavioral traits beyond annotations.

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

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

Two sentences with zero waste. Front-loaded with 'All 30 NBA teams' immediately conveys the scope and content.

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

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

For a simple directory listing with no parameters and an output schema, the description is complete. It mentions key fields and the tool's purpose, which is sufficient given the low complexity.

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

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

No parameters exist, so schema coverage is 100%. Description mentions output fields (ID, name, city, abbreviation, conference, division), adding value by specifying what the tool returns.

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

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

The description clearly states the verb (list/retrieve), resource (all 30 NBA teams), and purpose as a directory to resolve team names to numeric IDs for other tools. It differentiates from sibling tools like 'team' (singular) and others.

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 as a directory to resolve a team name into the numeric team_id required by other balldontlie tools,' providing clear context. Could be improved by explicitly mentioning when not to use or naming alternatives, but it is still very effective.

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?

Adds value beyond annotations by explaining deactivation vs deletion and historical availability. Annotations already indicate non-destructive, but description clarifies.

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 efficient sentences front-loading action, then ownership, then effect. 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?

Complete for a simple one-param tool. Explains outcome clearly. Lacks return value info but no output schema exists.

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

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

Schema coverage is 100% and description simply restates 'by id'. No additional meaning beyond the schema's parameter 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?

Clearly states the verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling 'subscribe' but does not explicitly name alternatives.

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?

Mentions ownership enforcement, implying when to use. Does not provide explicit when-not-to-use or alternative tools.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial context beyond this: the structured SEC EDGAR/XBRL path for financial claims, the grounded pipeline fallback, return verdict values, and crucial semantics around 'could_not_verify' (meaning the check didn't happen) vs. 'unsupported'. This is rich, non-redundant behavioral transparency.

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

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

The description is long but well-structured: it starts with natural-language examples, then explains the pipeline, return values, error semantics, and replacements. Every sentence provides useful information, though a few could be tightened. Overall it is appropriately sized for the tool's complexity and front-loaded with actionable examples.

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 paths, multiple verdicts, error states), the description is exceptionally complete. It covers return values, error semantics, the difference between 'could_not_verify' and 'unsupported', and even explains why it replaces multiple sequential calls. No output schema exists, so this description carries full responsibility and does so admirably.

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

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

Schema coverage is 100%, so the baseline is 3. The description itself does not add parameter-specific semantics; all parameter details (e.g., tolerance_pct override and default) are already fully described in the input schema. No additional meaning is provided in the description beyond what the schema supplies.

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 phrase ('natural-language claim verification') and defines the resource (fact-checking against authoritative sources). It clearly distinguishes from sibling tools by focusing on 'fact check' / 'verify the claim' and explicitly mentions it replaces 4–6 sequential calls, making it the go-to tool for claim validation.

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: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates internal routing for company-financial claims vs. other factual claims, giving clear context. However, it does not explicitly name alternative tools or provide when-not-to-use scenarios, so it stops short of a perfect 5.

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