Tcgdex

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds value by detailing the return structure (per-model scores, confidence, signals, raw_response), model selection cost implications, and combined view. 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 well-structured sentences with no waste. Front-loaded with the primary action and output, then covers optional parameters and use cases. Every sentence earns its place.

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

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

Despite no output schema, the description explains the return structure, scoring range, and model options. Required parameter is covered, optional ones are explained, and use cases are given. Sufficient for an agent to select and invoke correctly.

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

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

All 4 parameters have 100% schema coverage, and the description adds useful context: entity requires a name/query, models lists supported options, _apiKey explains Anthropic requirement, context disambiguates. Goes beyond the schema's basic type 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?

Description clearly states the tool probes LLMs for brand/product visibility and scores 0-100 per model. It specifies verb ('probe'), resource ('LLMs'), and output ('score visibility'), distinguishing it from sibling tools like ask_pipeworx or deep_research.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use free vs BYO key model. Missing explicit exclusion guidance for when not to use this tool, but context is clear.

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

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

Annotations already flag readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond this: it routes to 5,529 tools across 1,455 sources, fills arguments, returns pipeworx:// citation URIs, works on every tier, and handles news routing. This enriches the agent's understanding of the tool's operation.

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 ideal but every sentence provides value: domain coverage, routing behavior, alternates, and examples. It front-labels 'PREFER OVER WEB SEARCH' for immediate prioritization. While a bit verbose, it remains well-organized 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?

For a broad entry-point tool with no output schema, the description is thorough: it explains what it does, when to use it, how it differs from more specialized tools, what types of questions it handles, and what the response includes (structured answer with citations). This makes it comprehensive for an agent to decide when to invoke it.

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

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

Schema coverage is 100% (all 6 parameters are documented, with 5 as aliases for 'question'). The schema already explains that the main parameter accepts multiple aliases. The description does not add further parameter details, so it stays at the baseline for high schema coverage.

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

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

The description clearly states the tool answers factual questions by routing to thousands of verified sources and returning structured answers with citations. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its purpose specific and non-overlapping.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and directly names alternatives ('ask_pipeworx_grounded', 'deep_research') for different scenarios. It also provides example queries to illustrate appropriate usage, which is strong situational guidance.

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

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

Annotations already declare read-only, open-world, idempotent behavior. The description adds valuable context beyond that: live candidate routing improvements may be enabled, no candidate is currently active, and it is a full working router with no fallback. This clarifies the experimental and current-state 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 key point ('Beta version of ask_pipeworx') and provides four focused sentences covering identity, current status, usage, and functional guarantee. There is slight redundancy in saying it 'currently matches ask_pipeworx exactly' and 'Falls back to nothing — this IS a full working router,' but overall it is appropriately concise.

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

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

Given the tool's experimental nature and the high-confidence annotations/schema, the description is sufficiently complete: it explains what it is, why it exists, when to use it, and its current equivalence to ask_pipeworx. It does not detail the response format, but explicitly says the response shape is identical to ask_pipeworx, which compensates for the lack of an output schema.

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

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

Schema coverage is 100% with every parameter explicitly documented as an alias for 'question,' so the description does not need to add parameter-level detail. It only notes 'same arguments' as ask_pipeworx, adding minimal value beyond the schema, which is already sufficient.

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 ask_pipeworx_beta as a beta version of ask_pipeworx with an identical universal router, including the same 5,529 tools, arguments, and response shape. It distinguishes this tool from the stable ask_pipeworx sibling by framing it as the experimental routing edge.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It does not elaborate on when NOT to use it or how it differs from ask_pipeworx_grounded, but the beta/experimental framing supplies enough 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 show readOnly/openWorld/idempotent, and the description adds critical behavioral detail: it extracts only from tool results, returns explicit refusal reasons with specific enums, and costs an extra LLM call. This goes well beyond the structured annotations and gives the agent accurate expectations for failure modes.

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

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

The description is long but every sentence adds value: purpose, routing, extraction guarantee, return shape, refusal reasons, use cases, and cost tradeoff. It is front-loaded with the primary purpose and then provides necessary operational detail, with 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?

Despite no output schema, the description fully specifies the success return shape and all refusal reasons, explains routing across 5,529 tools, and covers behavioral nuances like data truncation. For a high-stakes, complex read tool, this is complete and self-sufficient.

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

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

Schema coverage is 100%, with each parameter's purpose and aliases documented in the input schema. The description doesn't add parameter-level detail, but the schema fully handles it; 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?

Description clearly identifies a specific verb ('EXTRACTS') and resource ('answer mode'), and distinguishes it from the sibling ask_pipeworx by emphasizing hallucination-resistance and grounded extraction. It cites concrete routing behavior and return structure, making the tool's unique role unmistakable.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and provides exclusions with an alternative ('prefer ask_pipeworx for casual lookups'). Also names the cost tradeoff of one extra LLM call, giving clear decision 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 extensively discloses behaviors beyond annotations: it describes the resolution process, classification, fan-out, response fields (market, analysis, evidence), resolver contract, parent event extraction, news fallback, safety mechanisms (low-confidence, closed markets, wide spreads), and cancellation rules. Annotations already indicate safe/read-only, but the description adds rich detail on edge cases and internal logic.

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 all-caps section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and logical flow. While not minimal, each sentence earns its place due to the tool's complexity. It is front-loaded with the main purpose and usage, making it efficient for an agent to parse.

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

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

Given the tool's complexity (multiple response shapes, fan-out logic, edge cases) and the absence of an output schema, the description comprehensively covers all aspects: input types, classification categories, fan-out examples, response fields, resolver behavior, safety mechanisms, and cancellation rules. It leaves no critical gaps for an agent to misuse the tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The description adds significant value by explaining concrete input formats (slug, URL, question text), providing examples, detailing the depth parameter's behavior and default, and clarifying the include_raw parameter's effect on response size. This goes well beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via data pulling). The verb 'Research' and resource are specific, and the tool distinguishes itself from siblings like ask_pipeworx by focusing on betting edge 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?

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear usage context. However, it does not explicitly state when not to use the tool or mention alternatives among sibling tools, so it misses the 'when-not/alternatives' part for a perfect score.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds detailed behavioral context: it pulls latest 10-K data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, and for drugs pulls FAERS adverse-event counts. It also clarifies sorting and output format. 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 longer than typical but every sentence adds value, with front-loaded examples and clear structure. Slight redundancy in listing query patterns could be trimmed, but it's justified by the tool's complexity.

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

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

Despite no output schema, the description compensates by describing return format (paired data + citation URIs) and edge cases (off-calendar fiscal years). For a comparison tool with 2 parameters, it covers all necessary context for correct usage.

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 significant meaning: it explains that type='company' retrieves specific financial metrics and type='drug' retrieves specific counts, and clarifies that values are tickers/CIKs or drug names. This greatly aids correct invocation.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific examples. It distinguishes from sibling tools like entity_profile by explicitly recommending this tool over sequential single lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides concrete query patterns like 'compare X and Y', 'which is bigger', etc., making it clear when to use this tool.

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

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

Even with readOnlyHint and idempotentHint annotations, the description adds rich behavioral disclosure: account/auth requirements, paid plan, gaps[] never invented, semantic excerpting of long records, timing expectations, and fetchable citations. 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?

Although long, every sentence carries essential, non-redundant information. Front-loaded with the account requirement, then logically organized from high-level purpose to specific behavioral details. No filler or repetition.

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

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

Despite lacking an output schema, the description fully specifies the return structure: findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop. Also covers expected latency ranges, making it comprehensive for a complex tool.

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

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

Schema covers 100% of parameters, but the description adds meaning well beyond it: explains depth tiers in terms of facet counts, gap recovery, contradiction scanning, paid requirement, and natural-language question suitability. The 'question' parameter is explicitly described as accepting broad/multi-part input.

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

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

States a specific verb-resource relationship: 'grounded multi-source research' across structured data sources, with clear scoping ('NOT open-web search') and explicit mention of decomposition and routing. Distinguishes itself from siblings by naming ask_pipeworx as the lighter alternative.

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 and when-not-to-use guidance: best for broad/multi-part questions over structured data, use ask_pipeworx for single lookups and for breaking/current news. Also warns about account requirements and paid tier for depth:'thorough'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; description adds that results are ready to call directly with full schemas, no second lookup needed. No contradictions, and the description provides useful behavioral context beyond annotations.

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

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

Description is front-loaded with purpose and is concise, with each sentence adding necessary information. No fluff; it efficiently conveys the tool's role and output.

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

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

Given no output schema, the description adequately covers what the tool returns (names, descriptions, full schemas). It also addresses the tool's role in a multi-tool environment, making it complete for a discovery tool.

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

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

Schema coverage is 100% and each parameter has a description. The description adds value by explaining that 'query' is a natural language task description and provides example queries, supplementing the schema's alias list.

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 finds tools by describing data or task, enumerates supported domains, and specifies it returns top-N results with full schemas. It distinguishes from sibling tools by advising 'Call this FIRST' when many tools are available.

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 (browse, search, discover tools) and recommends using it first. Does not explicitly list exclusions or alternatives, but the context implies it s for exploration before selecting a specific tool.

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

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

The description adds context beyond annotations: fans out across multiple sources, returns specific fields, mentions USPTO sunset with soft-fail, and news fallback. Annotations already indicate read-only, idempotent, non-destructive; description reinforces and details the 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 a single dense paragraph. While all content is valuable, it could benefit from bullet points or more structured formatting for easier scanning. Not overly verbose but not highly 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 no output schema, the description explains all return fields (cik, company_name, filings with URIs, fundamentals, patents with caveat, news, LEI). It is sufficiently complete for a broad-profile tool, though error handling or performance is not mentioned.

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%. Description adds meaning: type only 'company' for now, value must be ticker or zero-padded CIK, names not supported. This supplements 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 clearly states the tool function: 'full cross-source profile of a US public company in ONE parallel call.' It lists example queries and specific data sources (SEC, XBRL, USPTO, news, GLEIF) and distinguishes from siblings like resolve_entity and compare_entities.

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

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

Explicitly advises to prefer this tool over chaining single-source lookups for holistic views. States constraints: only supports ticker or CIK, names not supported (use resolve_entity first). Provides clear when-to-use guidance.

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

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

Annotations already indicate destructiveHint=true, and the description confirms deletion behavior. No contradictions. Lacks detail on return values or confirmation, but adequate for a simple operation.

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 front-loaded action; no extraneous 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 single parameter, no output schema, and simple destructive action, the description is complete and sufficient for effective tool use.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. Description adds no further meaning beyond the schema, so baseline 3.

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

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

The description clearly states 'Delete a previously stored memory by key', using specific verb and resource, and distinguishes from sibling tools like 'remember' and 'recall'.

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

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

The description provides explicit usage guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data' and suggests pairing with 'remember' and 'recall'.

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

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

Annotations declare read-only, idempotent, open-world, non-destructive. Description adds concrete behavior: fetches page, extracts title/description/key links, emits markdown. 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?

Well-structured paragraph starting with main purpose, then steps, then usage examples. Slightly wordy but no redundant sentences. Could be slightly tighter.

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 purpose, behavior, output format, and usage scenarios. With annotations covering safety and schema covering parameters, no critical gaps remain.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds context about return format ('single text blob') but does not significantly enhance parameter meaning beyond schema.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file for any URL', specifies the actions (fetch, extract, emit), and distinguishes from sibling tools by focusing on a specific output format.

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 cases (getting a client site indexed, drafting for own project, auditing competitor). Lacks explicit when-not-to-use or direct sibling comparison, but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. Description adds value by detailing the return fields (category, rarity, hp, etc.) and a high-quality image URL, which is beyond what annotations cover.

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

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

Single sentence that efficiently conveys purpose, input, and output. No wasted words.

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

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

Description is complete for a simple tool with one parameter and rich annotations. It covers purpose, input format, and output details. No missing critical 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 describes the single parameter 'id' with 100% coverage. Description adds an example value 'swsh3-136' but no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states it looks up a single Pokémon TCG card by TCGdex id, listing specific return details. This distinguishes it from sibling tools like search_cards (which searches multiple) and get_set (which retrieves sets).

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?

Clearly indicates when to use: to look up a single card by id. Implicitly suggests not for searching (use search_cards). No explicit alternatives or exclusions, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, signaling safe read-only behavior. The description adds value by detailing the return content: 'serie, release date, card counts, and the list of cards'. 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 a single, front-loaded sentence that efficiently conveys purpose and output. No unnecessary words.

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

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

For a simple lookup tool with one parameter and no output schema, the description sufficiently explains the return details. It could mention example IDs or edge cases (e.g., not found), but given the annotations and schema, it is complete enough.

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 'id' described. The description also mentions 'by its TCGdex id'. No additional semantics needed beyond what schema and description provide.

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: 'Look up a single Pokémon TCG (or other trading card game) set by its TCGdex id'. It specifies the verb 'look up', the resource 'set', and the unique identifier. The emphasis on 'single' distinguishes it from sibling 'list_sets' which lists all sets.

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 the tool (when you have a specific set ID). It does not explicitly mention alternatives like 'list_sets' for browsing sets, but the usage is well implied.

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 operation. Description adds that it returns id, name, card counts, and mentions get_set for full data. No contradictions.

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

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

Two concise sentences, front-loaded with core purpose, no unnecessary text.

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?

Adequately covers purpose and return fields for a simple listing tool. Could mention ordering or limits but not essential.

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, so baseline 4. Description does not need to add parameter 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?

Clearly states it lists all sets from TCGdex database, with id, name, and card counts. Distinguishes from get_set which provides full set details.

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 directs to use get_set for full set details, providing a clear alternative. Implicitly suggests list_sets is for overview but lacks explicit when-not-to-use.

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

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

Annotations already cover readOnly and non-destructive hints. Description adds value by specifying caller-specific filtering and the set of return fields, enhancing behavioral 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?

Two sentences: first declares purpose and return fields, second provides usage guidance. No wasted words, efficient and clear.

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 lists return fields. Input schema is simple and fully covered. Description is complete for this 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 only parameter 'include_inactive' already described in the schema. Description adds no additional parameter 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?

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides context for when to use, though no explicit when-not.

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 provide minimal info (all false), so the description carries the transparency burden. It discloses rate limits (5 per identifier per day), that it is free and doesn't count against quota, the token issuance/redemption flow, and that the team reads digests daily. No contradictions with annotations.

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

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

The description is long but every sentence earns its place, covering purpose, usage, exclusions, token flow, and limits. It is well-front-loaded with the core purpose. Some fringe details (roadmap impact) could be trimmed, but overall efficiently 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?

With no output schema and all-false annotations, the description compensates fully: it explains the feedback flow, token retrieval, rate limits, quota, and scope restrictions. An agent has all necessary context to invoke the tool correctly in both filing and follow-up modes.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage nuance: avoid pasting end-user prompts, the claim_token round-trip pattern, and how to describe issues in terms of Pipeworx tools/packs. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's function: telling the Pipeworx team something is broken, missing, or needs to exist. It explicitly lists feedback types (bug, feature/data_gap, praise) and is sharply distinguished from all sibling tools, being the only feedback mechanism in the catalog.

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

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

Provides explicit when-to-use criteria: use for bugs (wrong/stale data), feature/data_gap requests, or praise. It also gives an exclusion rule (only for tools from this Pipeworx connection, not other MCP servers) and instructs how to follow up with a claim_token. This is model-tier 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 it's read-only, idempotent, non-destructive. Description adds valuable context: data sourced from CF analytics-engine, no PII, caching behavior (5min-1h). 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?

Concise single paragraph with clear bullet-point use cases. Every sentence serves a purpose; no redundancy or 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?

For a simple tool with one optional parameter and no output schema, the description fully covers what is returned and how to interpret results. No gaps.

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

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

Schema has 100% coverage with description for the single parameter. Description adds interpretative guidance (shorter windows for hot signals, longer for steady-state demand). Baseline 3 is elevated due to added meaning.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows, with explicit use cases. It distinguishes itself from sibling tools like 'discover_tools' by focusing on trending/call volume.

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 three specific use cases (discovering hot data sources, confirming canonical choice, aligning use case). Lacks explicit exclusions or alternatives but gives strong contextual guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds extensive behavioral details: monotonicity checks, partition-sum validation, fill check against CLOB depth, placeholder filtering, and similarity thresholds. 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 verbose but well-structured with teletype and examples. For a tool with complex logic, the length is justified. Could be slightly reduced without losing key details.

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

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

Despite no output schema, the description explains the response format (opportunities[], partition_check with fields). It covers edge cases (low similarity, placeholders) and the fill check. An agent has sufficient context to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description goes beyond the schema by explaining that 'event' accepts full URLs and 'topic' is a seed question, and contrasts the two modes effectively.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, which are unique among sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use 'event' (for a specific market with slug) and 'topic' (for cross-event scanning). It recommends 'event' for a specific market but does not explicitly state 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: caching at the KV level for 1h, response structure with diagnostics showing why segments are empty, edge calculation details (NET of slippage, Kelly fractions, 24h-move warning), and filter skips. 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 lengthy but well-structured, front-loading the core purpose and then detailing model families, response segments, and knobs. Every sentence adds information, though some technical details (e.g., exact formula for Kelly calibration) could be moved to external docs to improve conciseness.

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

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

Given the tool's complexity (9 parameters, no output schema, three response segments, multiple filters), the description fully explains all components: response structure (by_segment, fed_candidates, diagnostics), tradeable-edge knobs, and edge calculation details. Context signals indicate high complexity, and the description meets that bar completely.

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

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

Schema coverage is 100% with clear descriptions for all 9 parameters. The description adds extra meaning for some parameters (e.g., 'Edge is evaluated NET of slippage' for min_edge_pp, explanation of min_partition_leg_kelly). While the description largely focuses on overall tool behavior, the added context on parameter interplay and defaults is valuable.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, using specific verb 'scan' and resource 'Polymarket markets'. It distinguishes from siblings like 'polymarket_arbitrage' and 'polymarket_edge_tracker' by focusing on Pipeworx-specific signal discovery.

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

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

The description provides explicit usage guidance: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It mentions tradeable-edge knobs for filtering but does not explicitly compare to sibling tools or state when not to use it, leaving some room for improvement.

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 rich behavioral context beyond annotations: explains it is read-only (consistent with readOnlyHint), describes data source (daily snapshots), response structure (tracked, expired, snapshot_dates), and limits (60-day TTL, decay from daily closes). 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?

Description is front-loaded with core question and structured with RESPONSE sections, but contains some redundancy (e.g., repeated explanation of decay computation). Could be more concise without losing clarity.

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

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

Given tool complexity (time-series analysis) and no output schema, the description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]), their significance, and operational limits (data gaps, TTL). It leaves little ambiguity for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining defaults ('days' default 14, 'window' default '1wk') and clarifying options ('max 30' though schema says clamp 2-30, minor inconsistency). Overall, it enhances understanding beyond schema alone.

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

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

Description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily Polymarket edges snapshots. It answers specific questions about edge duration and shrinking. The verb 'answers' and resource 'edge persistence and decay telemetry' are precise, and the tool distinguishes itself from siblings 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?

No explicit guidance on when to vs. when not to use this tool. While the description implies usage for assessing edge age and decay, it does not mention alternatives or exclusion criteria. Given many sibling tools, this is a gap.

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 readOnly, idempotent, and non-destructive. The description adds rich behavioral detail beyond that: it walks the CLOB order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and for basket mode explains per-leg fill details, thin_legs identification, and forced directional risk. No contradiction with annotations.

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

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

The description is relatively long but every sentence adds value. It is well-structured: first a one-sentence core purpose, then single-market mode details, then basket mode details, then usage guidance. It is front-loaded with the most important information. Could potentially be slightly shorter but appropriate given 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 the absence of an output schema, the description comprehensively lists all return fields for both modes (e.g., top_of_book, vwap_fill_price, verdict, per-leg fill details, thin_legs, max_clean_notional_usd, forced_directional_risk). It also explains the meaning of results (e.g., 'capture_ratio', 'profit_usd'). Given the tool's complexity, this is complete and actionable.

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

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

Input schema coverage is 100%, but the description adds meaningful context: clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S (shares per leg)' in basket mode. It also explains the default side auto-detection in basket mode. These details enhance understanding 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 a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It immediately distinguishes two modes (single-market and basket) and explicitly names sibling tools (polymarket_arbitrage, polymarket_edges) that this tool is meant to precede. The purpose is unambiguous and complete.

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 includes an explicit usage directive: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns when not to rely on theoretical edge (thin books, partial fills) and explains the specific risk of not using the tool (unhedged directional position). This is exemplary usage guidance.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds extensive behavioral details: safety fields, compatibility warnings, skipped counters, temporal alignment. 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 well-structured but somewhat long (200+ words). It front-loads purpose, then modes, response, safety. Each part earns its place given complexity, but a slightly tighter edit would improve conciseness.

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

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

No output schema, so description must explain return values. It does so by describing leg-by-leg prices, matched spreads, safety fields, and temporal alignment. Could include an example response, but overall adequate for an agent.

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

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

Schema coverage is 100%, so parameters are documented. Description adds meaning by explaining the two modes, giving concrete examples for topic, and clarifying override behavior. This enriches beyond schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage which are single-venue, making it unique.

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 explains two modes (topic shortcuts vs explicit tickers) and provides guidance on when to use which. Includes compatibility warnings and temporal alignment to help decide if spreads are meaningful. Mentions that most mapped topics are not tradeable, setting realistic expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (by identifier) and pairing instructions. 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?

Concise sentences front-loaded with main action. Includes examples and pairing. Could trim slightly but overall efficient.

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

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

For a simple one-param read tool with rich annotations, the description covers purpose, usage, scoping, and examples. No gaps given no output schema.

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

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

Schema covers the single parameter with description. Description adds examples and explains behavior when key omitted, plus pairing context. Adds 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 retrieves a value saved via remember or lists all keys if omitted. Distinguishes from siblings remember and forget by explicitly pairing with them. Examples solidify purpose.

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

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

Explicitly describes when to use: to look up context stored earlier without re-deriving. Mentions scoping and pairing with remember/forget. Could add when not to use, but context is clear.

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

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

Description describes a side effect (mark_read updates read status) which contradicts the readOnlyHint=true annotation, which asserts no side effects. As per guidelines, score is 1 due to 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?

Three sentences, front-loaded with purpose, each sentence adds new information (content, filters, mark_read behavior, alternative access). 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?

Explains return fields and mark_read side effect adequately. Mentions alternate access and polling suitability. Lacks explicit mention of limit and unread_only parameters, but schema covers them. Suitable for a low-complexity 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 parameter descriptions, baseline 3. The description adds value by explaining how type, since, and mark_read work in context, though limit and unread_only are not mentioned in the description but are in schema.

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

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

The description clearly states it pulls fired events from the subscription feed, listing specific fields returned and filter options. It uses a strong verb 'Pull' and specifies resource 'fired events'. Among sibling tools, none overlap directly, but the purpose is unambiguous.

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

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

The description explains filtering by type and since, the mark_read behavior for polling, and mentions an alternative access via a GET endpoint for scripts/dashboards. However, it does not explicitly compare to siblings like list_subscriptions or when to avoid using this tool.

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

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

Annotations already show readOnlyHint, idempotentHint, etc. Description adds details: fans out to three sources, soft-fails for USPTO, rate-limiting fallback for news. 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 relatively long but well-organized, starting with usage examples then detailing behavior and parameters. Every sentence adds value, though a slight trim could improve conciseness.

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

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

Given complexity and no output schema, the description covers return type (changes[] grouped by source, total_changes, citation URIs) and mentions source-specific behaviors. Lacks explicit output structure but sufficient for a rich 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%, but description adds substantial value: explains 'since' accepts ISO and relative formats with examples like '30d', '1y', and that 'value' accepts ticker or CIK. This goes well beyond the schema descriptions.

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

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

The description starts with concrete example queries like 'What's new with X' and explicitly states 'change feed for a company in the last N days/weeks/months'. It clearly distinguishes from sibling 'entity_profile' by directing to use that for static profiles.

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

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

Provides explicit when-to-use examples and an alternative tool: 'Use entity_profile instead when you want the static profile'. Also explains fallback behavior between GDELT and GNews, aiding correct invocation.

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?

Annotated as idempotent and non-destructive. Description adds key behavioral details: key-value storage, identifier scoping, 24-hour retention for anonymous, 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?

Single dense paragraph with all necessary information. Could be slightly more structured, but every sentence adds value. 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 write tool with 2 parameters and no output schema, the description fully covers purpose, usage, behavior, persistence, and relationship to siblings. No gaps.

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

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

Schema already provides descriptions for both parameters (key and value) with 100% coverage. Description adds naming conventions ('subject_property', 'target_ticker') and clarifies value can be any text, providing extra context beyond schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides concrete examples like resolved tickers, addresses, user preferences. It distinguishes from siblings 'recall' and 'forget'.

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: 'when you discover something worth carrying forward'. Mentions pairing with 'recall' and 'forget', and notes scoping and persistence differences for authenticated vs anonymous sessions.

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

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

Even though annotations already indicate read-only/idempotent/non-destructive, the description adds valuable behavioral details: graceful degradation of LEI/FIGI enrichment, explicit listing of unresolved identifiers (rather than omitting them), and the cascading lookup behavior. No contradiction with annotations.

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

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

The description is long but front-loaded with real-world queries and a clear purpose. Every sentence adds information (supported types, internal cascade, failure behavior), though the dense single-paragraph format could be slightly more scannable.

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

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

For a tool with only two parameters and no output schema, the description thoroughly covers output (canonical identifiers, unresolved list, citations) and edge cases (unavailable enrichment sources). It gives enough context for an agent to know what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by detailing what each type returns (e.g., 'cross-source identity spine' for company, 'RxCUI + ingredient + brand' for drug) and by giving examples like 'AAPL' and 'ozempic', going beyond the schema's basic field descriptions.

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

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

The description explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides concrete example queries. It distinguishes from siblings by positioning it as the 'FIRST' step when a name needs an ID, unlike entity_profile or compare_entities.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and lists supported types and input formats. However, it does not explicitly mention exclusions or alternative tools, so it stops short of a full 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds that it probes each entity and returns a ranked list, but no additional behavioral traits beyond what annotations imply. With rich annotations, the description's incremental 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?

Two sentences: the first describes the core functionality, the second provides a use case and output summary. No fluff, every sentence carries information. Perfectly front-loaded and concise.

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

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

No output schema exists, but the description describes the return: 'ranked list with score, confidence, signal density per entity'. Parameter descriptions are covered. For a tool with 4 parameters, this provides adequate completeness for an agent to understand usage and output.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by stating that entities should be 2-8 items and that the first is treated as the 'subject' for narrative. This extra context goes 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks them. The example use case ('does Claude know about us as well as our competitors?') distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly says 'Useful for competitive AI-marketing audits' and implies this tool is for comparisons. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to understand when to choose this over single-entity checks.

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

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

Annotations already provide readOnly, idempotent, openWorld hints. The description adds significant context: it is a composite call fanning out to two services, gracefully degrades with partial failures, and lists specific fields returned.

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

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

The description is front-loaded with the core purpose and well-structured. However, it is somewhat verbose with multiple clauses; a more concise version could improve scanability.

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

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

No output schema exists, so the description must fully describe return values. It does so comprehensively, listing summary fields, per-advisory details, links, and alternative versions, along with error handling behavior.

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

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

Schema coverage is 100% with clear descriptions for both 'package' and 'version' parameters. The description adds no additional semantic information beyond what the schema already 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 states the tool's purpose: a composite check for adding an npm package, covering license, advisories, bundle size, etc. It distinguishes from sibling tools by specifying that only NPM is supported in v1 and directs other ecosystems to different tools.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of an npm package. Also provides limitations (NPM only) and behavior on partial failures, including timeout expectations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds useful behavioral context: it returns brief matches with a thumbnail, and searches by name. It does not contradict annotations and provides additional transparency about the output format.

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, no unnecessary words. It starts with the action and immediately follows with the result and next steps. Every sentence adds value.

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

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

Given the tool has only 2 optional parameters, no output schema, and simple semantics, the description provides all necessary context: what it does, what it returns, and how to get full details via a sibling tool. It is complete for its complexity.

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

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

The input schema has 100% coverage, describing both parameters (`name` and `limit`) with examples. The description adds no new parameter semantics beyond the schema, simply stating 'search by name'. The baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the action (search), resource (Pokémon TCG and other trading card game cards by name in the TCGdex database), and what is returned (brief matches with id, localId, name, image thumbnail). It also distinguishes from the sibling tool `get_card` by directing users to use that for full details. The title 'Search Cards' aligns well.

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 indicates when to use this tool (to search cards by name) and explicitly recommends using `get_card` for full details with an ID. However, it does not explicitly state when not to use this tool or mention any prerequisites or limitations, but the context is sufficient for appropriate use.

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 not destructive. Description adds detailed behavioral traits: embedding model (BGE-base-en), chunking (500-char overlapping windows), similarity measure (cosine), maximum input size (200K chars, truncated with flag), and output includes character offsets. 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 sentences, no filler. First sentence states core purpose. Second provides usage guidance. Third gives pairing and context. Fourth gives technical details. Efficient and well-structured.

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

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

Despite no output schema, description covers return format (passages with offsets and scores). Explains internal mechanics, limitations, and use case. Combined with rich annotations, the description is fully complete for an agent to select and invoke correctly.

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

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

All three parameters have schema descriptions (100% coverage). Description adds value by clarifying 'text' max size (200K chars), giving query examples, and explaining 'limit' as 'top-N passages'. Schema already provides basics; description enhances with real-world usage 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?

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling 'ask_pipeworx_grounded' by explaining pairing. No ambiguity.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes context-saving benefit. Provides usage pairing with 'ask_pipeworx_grounded'. Does not include explicit when-not, but the use case is clear.

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

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

Discloses behavioral traits beyond annotations: requires OAuth, returns new ID, delivery limitations (SMS cap, webhook auto-disable after 10 failures). Annotations indicate idempotent and not destructive; description confirms creation and adds details. 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?

Single paragraph packs all necessary info without wordiness. Logically orders: purpose, requirement, types, delivery. Could benefit from bullet points for readability, but no redundancy. Every sentence contributes.

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

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

Given the tool's complexity (multiple types, parameters, delivery modes, prerequisites), the description covers return value, authorization, type-specific configs, delivery options, and failure behaviors. Without output schema, it adequately describes the return (subscription id). No missing essential details.

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 meaning: explains each type (e.g., sec_8k items codes, polymarket_edge topics), params object with examples, delivery object with constraints (phone verification, webhook signing). Goes far beyond the schema's minimal descriptions.

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

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

The description clearly states the action ('create a proactive monitoring subscription') and the resource ('live-data event stream'), with explicit return value ('Returns the new subscription id'). It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation, and details types and delivery channels.

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 prerequisites (Pipeworx OAuth account), lists supported types with parameters, and delivery channel constraints (phone verification, daily caps, webhook restrictions). Implicitly guides when to use recent_alerts instead for pulling. Lacks explicit when-not-to-use statements but offers clear 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool returns tool+argument shapes from the live catalog, which is useful context beyond annotations. 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 common user phrasings and is detailed, but every sentence contributes value. Slightly longer than necessary but still efficient for the complexity.

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

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

No output schema, but the description explains the return format (category-bucketed example questions with tool+argument shapes). For a discovery tool, this is sufficiently complete given the annotations and schema richness.

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

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

Schema coverage is 100% and the description elaborates on the topic parameter with concrete examples (finance, pharma) and explains the default behavior when omitted, fully compensating for any lack of schema detail.

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

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

The description uses specific verbs ('returns category-bucketed example questions') and clearly states the resource (Pipeworx capabilities). It distinguishes from siblings like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides alternative queries. It also explains how to call meta-tools, giving clear when-to-use guidance.

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

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

Description adds important behavioral context beyond annotations: ownership enforcement, soft deactivation (not deletion), and historical event availability. It does not contradict annotations; in fact, it explains the meaning of 'destructiveHint: false' and 'idempotentHint: true' in practical terms.

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 that cover the core action and key behavioral details without any fluff. Front-loaded with the main purpose, then adds important context.

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 one parameter, no output schema, and good annotations, the description covers what the tool does, ownership constraints, data effect, and relation to history. No missing necessary 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?

The single parameter 'id' is fully described in the schema ('Subscription id (uuid) returned by subscribe'). The description reinforces this but does not add new information. With 100% schema coverage, baseline is 3.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', and distinguishes from siblings like 'subscribe' (creates) and 'list_subscriptions' (lists). Ownership enforcement and soft deletion differentiate it further.

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

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

The description explains ownership enforcement and the soft-deactivation behavior, implying when to use (stop own alerts) and what happens to data. However, it does not explicitly mention when not to use or suggest alternatives, which is acceptable but not perfect.

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

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

Goes well beyond the annotations with critical behavioral details: the distinction between 'could_not_verify' (a failure, not evidence) and 'unsupported' (no source), the routing logic, and the performance note about replacing 4-6 sequential calls. 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?

Despite being long, every sentence delivers unique value: examples, usage, routing, return values, and critical caveats. The structure is logical, moving from user intent to implementation to result interpretation. 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?

No output schema exists, so the description fully covers return values: verdict enum, actual value with citation, reasoning. It also explains error semantics and performance benefits. For a tool of this complexity, the description is remarkably 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 covers 100% of parameters with clear descriptions. The description adds context about percent-delta math and tolerance overriding, but does not significantly enhance parameter understanding beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources. It includes specific example phrasings ('Is it true that…', 'fact check') and describes the dual-path mechanism. It distinguishes itself from research tools by focusing on fact-checking with verdict outputs.

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?

States 'Use whenever the agent needs to check whether something a user said is factually correct,' providing explicit usage context. It also explains the two internal paths for financial vs. other claims. However, it does not name alternative tools or explicitly state when not to use other tools, so it falls short of the highest bar.

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