Thegamesdb

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds value by detailing default model, optional Anthropic integration with BYO key, and the return structure including per-model score, confidence, signals, raw_response. 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 three sentences with no filler. It front-loads the main purpose and then adds key usage details efficiently.

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

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

Despite no output schema, the description fully explains the return format. All four parameters are covered in both schema and description. No missing critical information for tool invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining default model behavior, that _apiKey is only needed for anthropic, and that context disambiguates. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it, with specific verb 'Probe' and resource 'LLMs'. It distinguishes from sibling tools implicitly by its unique function, but does not explicitly differentiate from similar tools like 'scan_competitor_ai_presence'.

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 usage contexts such as 'AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains default model vs paid Anthropic option. However, it does not specify when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it routes among 5,724 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs, as well as noting it is one fast call and works on every tier. This goes beyond what annotations alone convey.

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 nearly every sentence earns its place by covering scope, examples, alternatives, and escalation behavior. The key directive 'PREFER OVER WEB SEARCH' is front-loaded, and the rest is organized from general guidance to specific examples to escalation rules. It is dense rather than bloated.

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

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

For a tool with a simple one-parameter schema and no output schema, the description carries the full weight of context: when to use, when not to use, alternatives, natural-language input expectations, internal routing behavior, citation output, and news edge cases. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The schema covers all six parameters at 100%, and all are aliases for the single 'question' field. The description adds value by giving trigger phrases and concrete natural-language examples that shape what should be passed, e.g., 'current US unemployment rate' and 'patents Tesla was granted last month'. This helps the agent construct better values even though the schema already documents the field types.

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

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

The description uses strong actionable verbs and a clear resource: it is a question-routing tool that prefers authoritative structured data over web search. It names concrete domains and example queries, and explicitly differentiates itself from ask_pipeworx_grounded and deep_research. This makes its purpose unmistakable and distinguishes it from siblings.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also defines escalation conditions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. It even handles the breaking-news edge case by stating that ask_pipeworx already routes to live news.

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

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

The description adds substantial behavior beyond the readOnly/idempotent/openWorld annotations: it discloses that candidate routing improvements may be live under test, that no candidate is currently active, that it is a full working router with no fallback, and that results are compared against the stable router. This is exactly the kind of experimental-risk transparency an agent needs.

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 and information-dense, but it repeats the 'identical/exactly like ask_pipeworx' point three times. Each sentence adds some value, though tightening the redundancy would improve 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?

For a beta router with no output schema, the description covers what the tool does, its current state, how to invoke it, how it relates to the stable sibling, and that it does not degrade to a fallback. This is enough for an agent to use it correctly.

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

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

Schema coverage is 100%, and the schema already documents the question parameter plus all five aliases. The description only says 'same arguments' without adding parameter-level detail, so it does not increase semantic understanding of the parameters 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 identifies the tool as a beta variant of ask_pipeworx and a universal router over 5,724 tools. It distinguishes itself from stable ask_pipeworx by explicitly stating the beta/experimental status and noting that it currently matches ask_pipeworx exactly.

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 states when to use the tool: 'when you want the newest routing.' It also names the stable router as the comparison baseline and says to use it exactly like ask_pipeworx, giving the agent a concrete usage instruction and an implied alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, but the description adds substantial behavioral disclosure: it fetches data through routing, extracts the answer using only the tool result, and returns a structured refusal object with specific refusal reasons. This goes well beyond the structured metadata.

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

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

The description is dense but every clause earns its place: it states the mode, explains the routing and extraction behavior, lists the return contract, names refusal reasons, gives concrete use cases, and includes a cost tradeoff with the sibling. Key information is front-loaded with 'Hallucination-resistant answer mode...' leading the sentence.

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

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

With no output schema, the description fully documents the return shape, including success fields and refusal reasons, plus error classes. It also provides enough context about cost, routing, and appropriate use cases for an agent to invoke it correctly. Nothing essential for safe, correct selection or invocation is missing.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter and its aliases. The description reinforces that the input is a natural-language question but adds no parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the semantic weight.

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

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

The description identifies a specific verb-resource pairing: it is a grounded, hallucination-resistant answer mode for ask_pipeworx. It distinguishes itself from the sibling ask_pipeworx by explicitly labeling itself as the grounded variant and by describing its extract-from-fetched-data behavior. The scope is clear: return a supported answer or an explicit refusal.

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

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

The description gives explicit when-to-use guidance: use it when an answer will be quoted, cited, or acted on, such as financial verdicts, legal claims, medical lookups, or public statements. It also gives a when-not-to-use directive, saying to prefer ask_pipeworx for casual lookups because grounded mode costs an extra LLM call. This is strong routing guidance relative to its sibling tools.

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

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

The description extensively details behavior beyond annotations: resolution process, fan-out examples, response shapes, resolver contract, parent event extraction, news fallback fields, safety short-circuits (low confidence, closed markets), wide spread warnings, and cancellation rule parsing. This far exceeds the baseline provided by readOnlyHint and idempotentHint.

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

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

The description is well-structured with labeled sections (classifiers, fan-out examples, response shapes, etc.) and is front-loaded with the main purpose. While verbose, each section provides necessary detail for a complex tool. One minor improvement could be slightly tighter phrasing, but overall it earns its length.

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

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

Given no output schema, the description comprehensively explains return values (result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields) and covers edge cases (low confidence, closed markets, wide spread, cancellation rules). This fully equips the agent to interpret and use the tool's output 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%, but the description adds meaning: it explains the 'market' parameter accepts slug, URL, or question text; 'depth' options are defined in enum descriptions (quick vs thorough); 'include_raw' is described for summarized vs full payload. The description also provides examples. This adds value beyond the schema definitions.

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

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

The description explicitly 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), actions (research, pull data), and acceptable input formats (slug, URL, question text). This clearly distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence, checking cancellation rules before sizing, and notes short-circuit conditions. However, it does not explicitly state when NOT to use this tool or suggest alternative tools.

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

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

Annotations indicate read-only, idempotent, and non-destructive. The description adds behavioral details: pulls latest 10-K data for companies with correct fiscal year handling, FAERS data for drugs, results sorted by primary metric, and returns paired data with citation URIs. 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 relatively compact (4 sentences) and front-loaded with trigger phrases. Every sentence adds value: trigger examples, usage preference, data sources per type, sorting, and return format. Could be slightly more concise but still effective.

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 return format ('paired data + pipeworx:// citation URIs per entity'). It covers entity types, data sources, fiscal year handling for companies, and metric sorting. The tool's purpose and behavior are fully described.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds meaning beyond schema: for 'type', it explains what data is pulled for company vs drug (SEC EDGAR/XBRL financials, FAERS counts) and for 'values', it gives examples (tickers for companies, drug names). It also describes sorting behavior.

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 like 'Compare' and provides trigger examples ('X vs Y', 'rank these companies'). It clearly states the tool compares 2-5 companies or drugs in one call, and explicitly distinguishes from sequential lookups by saying 'ALWAYS PREFER over sequential single-pack 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 gives explicit guidance on when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete use cases like 'which is bigger / better / larger / more profitable' and specifies the number of entities (2-5). It implicitly advises against using for single-entity queries.

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

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

Even with annotations covering read-only/idempotent safety, the description adds a great deal: authentication requirements, paid-tier depth, parallel routing, the findings packet shape, citation_uri semantics, gaps[], contradictions[], semantic excerpting, and latency. There is no contradiction with the annotations; openWorldHint does not conflict with 'not open-web search' since the tool grounds in structured sources.

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

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

The description is long, but every sentence carries operational value: auth, alternatives, output format, gaps behavior, depth semantics, and latency. It is front-loaded with the most critical constraint (account requirement) and the alternative tool, and the density is justified by the tool's complexity.

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

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

There is no output schema, so the description correctly explains the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop fields. It also covers latency, prerequisites, and failure modes. An agent has everything needed to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds meaningful behavioral nuance for depth values beyond the schema by explaining what 'standard' and 'thorough' do at the research level, and clarifies that 'question' may be broad/multi-part. This exceeds the baseline for fully-covered schemas without duplicating 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 states a specific action ('grounded multi-source research'), a clear resource ('Pipeworx's 1497 structured data sources'), and explicitly contrasts itself with open-web search and ask_pipeworx. An agent can immediately tell this tool is for broad structured-data research, not casual or breaking-news queries.

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

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

The description gives concrete decision rules: use ask_pipeworx when not signed in, for single lookups, and for breaking/news topics; use deep_research for broad/multi-part structured questions. It even explains when results will be empty (topics outside the structured catalog), making the when-to-use boundary unusually explicit.

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

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

The description adds value beyond annotations by stating the output format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This provides behavioral detail that annotations alone do not convey.

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

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

The description is a single paragraph that front-loads the core purpose and includes every necessary detail. It could be more structured (e.g., bullet points) but no sentence is wasted, earning above average 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 6 parameters, no output schema, and many sibling tools, the description is complete. It covers purpose, usage, output format, and parameter behavior, providing a full picture for an agent to use the tool correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by clarifying the alias parameters (q, task, search, description) and the default limit, reinforcing parameter usage beyond what the schema already provides.

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 'Find tools by describing the data or task' and lists many specific domains, establishing a specific verb+resource. It distinguishes itself from sibling tools as the discovery tool.

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 when you need to browse, search, look up, or discover what tools exist' and advises 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear usage context but does not explicitly state when not to use it or give alternative tools.

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

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

Discloses behavioral traits beyond annotations: fans out across multiple sources, mentions USPTO sunset and soft-fail, GDELT→GNews fallback, names not supported, and lists exact return fields. Annotations already indicate readOnly/idempotent, but description adds rich operational detail.

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

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

Description is long but information-dense, with example queries upfront, then clear explanation of functionality and return fields. No wasted sentences, though could be slightly more concise.

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

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

With no output schema, description fully explains return values (cik, company_name, recent_filings, fundamentals, patents, news, LEI), including caveats like USPTO sunset and fallback. Complete for an agent to understand what the tool provides.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning by explaining that value can be ticker or CIK (zero-padded), and that names are not supported, and type currently only supports 'company'. This goes beyond the schema's basic definitions.

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

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

Clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists the specific data sources and fields. Differentiates from sibling tools like resolve_entity and chaining individual 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?

Explicitly advises to prefer this tool over chaining single-pack lookups for holistic views, and instructs to use resolve_entity first if only a name is available. Provides example queries to trigger 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 provide destructiveHint=true and idempotentHint=true. The description adds that it deletes a memory by key and mentions 'clear sensitive data' as a use case, but does not disclose additional behavioral traits such as irreversibility or whether it returns a confirmation. This is adequate but not beyond the annotations.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds value. No extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage guidelines, and pairing. It is complete enough for an agent to use correctly, though it could optionally mention what happens if the key does not exist or if deletion is successful.

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 a clear description for the only parameter ('Memory key to delete'). The tool description does not add extra semantics beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the action (delete), the resource (a memory by key), and the context (previously stored memory). It distinguishes from siblings like 'remember' and 'recall' by implication, as it pairs with them rather than duplicating their functions.

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 when-to-use scenarios are given: 'context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall,' which indirectly indicates when not to use it (e.g., for storing or retrieving). No explicit alternatives or exclusion criteria are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown, which enriches understanding without contradiction.

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

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

Single paragraph under 70 words, front-loaded with core purpose, then functional detail, then use cases. Every sentence serves a purpose; 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?

For a simple tool with 2 parameters, full annotation coverage, and no output schema, the description explains the process, output format, and usage scenarios completely. No gaps identified.

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

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

Schema coverage is 100% with good descriptions for both parameters. The tool description does not add any additional meaning to the parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description uses specific verb 'generate' and resource 'llms.txt file'. It clearly states the action: produce a standard file for AI crawlers by fetching a page and extracting key info. Distinguishes from siblings like scan_competitor_ai_presence by being a file generation tool rather than analysis.

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

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

Explicitly lists use cases: getting client indexed, drafting own project, auditing competitors. Does not include when not to use but context is sufficient. Output note about dropping at site-root aids deployment decision.

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, openWorldHint, and destructiveHint=false, providing safety profile. Description adds that the response includes a front boxart image URL, exceeding annotation coverage. 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 sentence plus a clear example. No unnecessary words or redundant information.

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

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

No output schema, so description bears responsibility for return value clarity. 'Full metadata' is vague; only the image URL is specified. Missing details on error handling, rate limits, or optional API key behavior. Adequate but incomplete for a simple read tool.

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

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

Schema has 100% coverage for both parameters. Description includes an example and mentions the id parameter but does not add meaning beyond 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 the tool retrieves full metadata for a single game using its TheGamesDB id, and specifies inclusion of the front boxart image URL. This distinguishes it from sibling tools like search_games which likely return multiple games.

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

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

Usage is implied: use when you have a specific game id. However, no explicit when-not-to-use or alternatives are provided. The example clarifies input but lacks 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=true, destructiveHint=false, idempotentHint=true. The description adds no further behavioral traits beyond stating 'List' which is consistent. Minimal added value.

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

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

Extremely concise: two sentences and an example. Front-loaded with the main purpose, no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description sufficiently covers what the tool does and why it's useful. No gaps remain.

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

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

Schema coverage is 100% and already describes the _apiKey parameter. The description does not discuss parameters at all, so it adds no additional meaning beyond the schema. Baseline 3 applies.

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

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

Clearly states the action ('List'), the resource ('all game genres known to TheGamesDB'), and what it returns ('id, name'). Distinguishes itself from siblings like list_platforms and search_games.

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

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

Provides explicit use case ('Useful for resolving genre ids') and a concrete example. Does not mention when not to use or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the specific returned fields (id, name, alias) but no additional behavioral traits beyond what annotations imply.

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 with no superfluous content. The example is compact and informative. Every element 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?

Given the tool's simplicity (no required parameters, no output schema), the description adequately covers purpose, return fields, and usage. It lacks mention of pagination or limits, but for a list-all tool this is acceptable.

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

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

Schema description coverage is 100% (the _apiKey parameter is documented). The description does not mention the parameter, but the schema already provides the necessary meaning. Since no additional value is added, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists all gaming platforms from TheGamesDB and specifies the returned fields (id, name, alias). The example and mention of resolving platform IDs add clarity. It is distinct from sibling tools like get_game or search_games.

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

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

The description explicitly says it is useful for resolving platform IDs, providing a clear use case. It does not explicitly state when not to use or name alternatives, but the context and sibling list make it sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by listing return fields and implying it returns only active ones by default. 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 sentences, front-loaded with output fields, and a concise usage note. Every word earns its place.

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

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

For a simple list tool with one optional parameter and comprehensive annotations, the description covers return fields and usage scenarios completely. No output schema needed.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. The tool description does not add significant parameter information 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 action ('List the caller's active subscriptions') and specifies the returned fields. It 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?

The description provides explicit use cases: review monitoring before adding more or find an id to cancel. It could mention when not to use, but the context is clear enough.

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

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

With all annotations false (no readOnly, destructive, etc.), the description carries the full burden and delivers. It discloses the claim_token return/flow, rate limiting ('Rate-limited to 5 per identifier per day'), free usage, and that the team reads digests daily. This goes well beyond the minimal safety hints in 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 text is a single dense paragraph but front-loads the core purpose in the first sentence. Every subsequent sentence adds crucial context: scope restriction, claim_token behavior, rate limit, and pricing. It is slightly long but efficient for the behavioral complexity it must convey.

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 (nested context object, no output schema, claim_token lifecycle), the description covers the full flow: what happens on filing (returns claim_token), how to check status later (pass token back), and constraints (rate limit, scope). There are no significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by mapping the 'type' enum to real-world scenarios (bug = wrong data, feature = wish, praise = worked well) and explaining the claim_token workflow contextually. It doesn't fully repurpose the schema but enhances it enough for a 4.

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

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

The description opens with a strong, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team) and distinguishes this tool from sibling tools like ask_pipeworx or discover_tools by focusing on reporting feedback rather than querying data.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and instructs users to file with other servers for third-party tools, which 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?

Beyond annotations (readOnly, idempotent, etc.), the description adds: source (CF analytics-engine), no PII, caching behavior (5min-1h). This fully discloses behavioral traits without contradiction.

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

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

Three concise sentences plus a bullet list. Each part adds value; slightly longer but front-loaded with core purpose. Could be more terse but still 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?

All essential info is present: what it returns (top tools, packs, volume), single optional param, caching, data source. No output schema needed given clear description of return content.

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

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

Schema coverage is 100% for the single parameter ('window'). The description adds semantic value by explaining how shorter vs. longer windows affect results (hot vs. steady-state), beyond the enum 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?

The description clearly states the tool returns trending data (top tools, packs, call volume) from AI agent calls on Pipeworx. It is distinct from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on aggregated trends.

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

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

Three explicit use cases are provided (discovering hot data, confirming canonical tool, checking alignment). The description implies when to use this tool vs. specific query tools, but no explicit when-not or alternatives given.

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

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

Annotations already declare safe read-only behavior, and the description adds extensive behavioral context: monotonicity checks, partition_sum logic, fill check vs book depth, semantic anchor for cross-event, placeholders filter. 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 thorough and well-structured with sections for modes, fill check, etc. A few sentences could be tightened, but overall efficient given 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 exists, but the description comprehensively covers all response fields, fill check logic, and edge cases. An agent can fully understand how to use the tool and interpret results.

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

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

Schema coverage is 100%, but the description adds significant value: explains event slug format, that full URLs work, what topic seed question does, and how each mode operates. 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the unique arbitrage detection approach.

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

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

Explicitly tells when to use each parameter: no args for trending scan, `event` for specific market, `topic` for cross-event scan. Provides recommendations (e.g., event mode for specific markets) and when not to trade (realizable_edge_pp <= 0).

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 and destructiveHint, so the description adds significant value by detailing the three model families, the response structure with by_segment and diagnostics, caching behavior (1h at KV level), and the 24h-move warning. No contradictions with annotations.

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

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

The description is long but extremely dense with useful information. It front-loads the main purpose and then structures the segments with numbered lists. Every sentence earns its place, though some model details (e.g., 'lognormal barrier from 90d FRED log-returns') could be trimmed. Still, no fluff and well-organized.

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 with 9 parameters, no output schema, and three distinct segments, the description is remarkably complete. It explains the response structure (by_segment, diagnostics, fed_candidates), caching, edge cases (why partition arbs have zero Kelly), and tradeable-edge knobs. It fully compensates for the lack of 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?

With 100% schema coverage, baseline is 3, but the description adds substantial extra meaning: for slippage_pp, it explains Polymarket's fee structure and suggests adjustments; for min_partition_leg_kelly, it clarifies why partition arbs have zero parent kelly and how this knob works; for category_filter, it explains segment combinations. 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. The phrase 'what should I bet on today' gives a clear use case, and the specific mention of multiple model families distinguishes it from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly positions the tool for discovering betting opportunities without paging hundreds of markets. It explains when to use (discovery) and provides context about Fed bets being excluded from ranking due to data limitations. It implicitly differentiates from siblings by focusing on Pipeworx disagreement rather than arbitrage or fill risk.

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 substantial behavioral context beyond annotations: it details data sourcing (daily snapshots), time-series computation, trend/decay indicators, and limits (60-day TTL, daily closes). 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 dense yet well-structured, with clear sections for purpose, parameters, response format, and limits. Every sentence earns its place, but slightly verbose for a concise tool description.

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

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

Despite lacking an output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) with field details and behavioral limits. It is complete for a read-only telemetry 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?

Parameters are fully covered in the schema (100% coverage). Description adds defaults, clamping range for 'days', and clarifies 'window' as snapshot family, enhancing semantics 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 explicitly states the tool's purpose: edge persistence and decay telemetry. It uses a specific verb ('answers') and resource ('polymarket_edges snapshots'), and implicitly distinguishes from sibling 'polymarket_edges' by focusing on historical persistence.

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 clearly indicates when to use this tool by framing the question it answers. While it implies alternatives (e.g., current edge data from sibling 'polymarket_edges'), it lacks explicit when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and for baskets details thin legs and forced directional risk. It warns about partial fills converting arb into unhedged positions, which is beyond the annotations.

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

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

The description is long but well-structured with mode headers and bullet-style return fields. Every sentence adds value, though some details (e.g., 'each share pays $1') are slightly redundant. It is front-loaded with the core purpose and usage guidance.

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

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

Despite lacking an output schema, the description thoroughly covers return fields for both modes, including top_of_book, vwap_fill_price, slippage_pp, profit_usd, thin_legs, and more. It also explains the dominant loss mode, making the tool's outputs and risks comprehensible without additional documentation.

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

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

Schema coverage is 100%, but the description adds important context beyond schema descriptions: it explains default size_usd behavior (max spend vs target proceeds), basket size interpretation as settlement notional, and automatic side detection. This enriches the meaning for 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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It uses specific verbs and resource names, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why, citing the risk of unhedged positions from partial fills. This provides clear context and excludes inappropriate usage.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the token-overlap matching logic, compatibility codes and when they can be non-empty, skipped legs, unclassified legs never being paired, gross-vs-net spread (Kalshi fees not modeled), and temporal_alignment null semantics. This is exceptional transparency for a no-output-schema tool, and nothing contradicts the annotations.

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

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

Very dense and long, but organized with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, fees_note) and front-loaded with the core purpose. Every section carries operational value for a complex tool with no output schema, though the sheer volume of caveats requires careful reading.

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

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

For a tool with no output schema and a rich result shape, the description covers input modes, response contents, safety codes, skipped-leg behavior, temporal alignment semantics, and fee caveats. An agent has enough context to invoke either mode and interpret warnings correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it lists all topic shortcut values, gives concrete examples of ticker/slug formats, explains the override relationship to the topic-mapped side, and clarifies that both modes run the identical matcher. This elevates it above schema-only documentation.

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

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

States a specific verb+resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. This clearly distinguishes it from siblings like polymarket_arbitrage and polymarket_edges. The title 'Polymarket–Kalshi Spread' reinforces the exact scope.

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

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

Explicitly defines two mutually exclusive input modes (topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug), says both use the same matcher, and warns that pre-mapped topics are often not tradeable. It does not explicitly compare itself to sibling tools, so when-to-use versus alternatives is only implied rather than named.

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 safety profile (readOnlyHint, idempotentHint, destructiveHint). Description adds scoping details ('anonymous IP, BYO key hash, or account ID') and context about listing all keys, which supplements annotations without contradiction.

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

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

Concise, well-structured sentences with no wasted words. Main action front-loaded, supporting details follow logically.

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 retrieval and listing, scoping, and pairing with siblings. Lacks explicit mention of error handling (e.g., key not found), but for a simple read tool with no output schema, it is sufficiently complete.

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

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

Schema has 100% coverage with parameter description. Description reinforces the behavior of omitting key (list all keys) and adds meaning by explaining the retrieval purpose, exceeding the schema-only baseline.

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

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

Description clearly specifies the action ('retrieve a value previously saved via remember, or list all saved keys') and distinguishes from sibling tools like remember and forget by naming them directly.

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 ('look up context the agent stored earlier') and pairs with siblings ('Pair with remember to save, forget to delete'), guiding when to use vs alternatives.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds that mark_read:true causes a state change (marking events as read), which is beyond the annotations. It also describes the feed as persisted and explains the effect of mark_read on subsequent calls. This provides valuable behavioral context.

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

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

The description is concise with three sentences plus an additional note. It is well-structured: purpose, output fields, filtering and marking behavior, and alternative access. No unnecessary words, every sentence adds value.

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

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

Given no output schema, the description explains the return structure (source, citation_uri, payload). All parameters are covered with their effects. It also mentions polling suitability and an alternative access method. For a read-only list tool, this is complete and informative.

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 all 5 parameters with descriptions. The description enhances this by giving examples (e.g., type 'sec_8k'), explaining ISO timestamp for since, and describing the effect of mark_read and unread_only. This adds meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed' and specifies the returned data (source, citation_uri, raw payload). It is unambiguous and distinguishable from sibling tools like 'list_subscriptions' and 'subscribe'.

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 guidance on filtering by type and since, and mentions that polling works fine. It also references an alternative REST endpoint for scripts and dashboards, giving context on when to use this tool vs. that. Lacks explicit exclusions but is sufficient for usage.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds valuable behavioral details: parallel fan-out, source fallback logic, and soft-failure for patents. 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?

Every sentence earns its place, front-loaded with example queries, and efficiently covers sources, parameters, and return structure without redundancy.

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

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

Despite no output schema, the description states return structure (changes[], total_changes, citation URIs). All three parameters are fully documented, and the tool's complexity is well-addressed.

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

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

Schema coverage is 100%, but the description adds significant meaning: relative time shorthand for 'since', zero-padded CIK format for 'value', and permissible 'type' values. Goes well beyond the schema.

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

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

The description clearly states the tool's purpose as a 'change feed for a company in the last N days/weeks/months' with concrete example queries. It distinguishes from the sibling 'entity_profile' by specifying when to use each.

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 (recent changes) and when-not-to (use entity_profile for static profile), along with fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail).

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 non-read-only, idempotent, non-destructive. Description adds scoping by identifier and explicit persistence rules for authenticated vs anonymous users, beyond annotation content.

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 verb and purpose, no redundant information. Every sentence provides 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?

With no output schema, description fully explains storage mechanism, scoping, and retrieval methods. Complete for a simple store tool.

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

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

Schema covers both parameters with descriptions. Description adds naming conventions (e.g., 'subject_property') and value type (any text), enhancing schema 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?

Clearly states the tool saves data for reuse across conversations/sessions, with specific examples. 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 describes when to use (discover something worth carrying forward) and pairs with recall and forget. Addresses scoping and persistence duration.

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

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

The description goes well beyond the readOnly/idempotent annotations: it documents ambiguity handling (`figi_candidates`), explicit `unresolved` output, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal endpoint cascading. These traits are context an agent could not infer from annotations alone.

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 and dense, but it is front-loaded with purpose, structured by entity type, and every major clause carries useful information. It slightly exceeds minimal conciseness due to heavy parentheticals, but this is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly covers what the agent should expect: returned identifier fields, candidate selection on ambiguity, explicit unresolved fields, ownership data, and graceful degradation. An agent has enough context to call the tool correctly and interpret its results.

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

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

Although schema coverage is 100%, the description adds substantial meaning: ticker/CIK/ISIN/name accepted for company, brand/generic accepted for drug, and a critical warning to pass only the issuer name for bonds, not the full noun phrase. This materially improves correct invocation beyond the schema.

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

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

The description opens with concrete user phrasings ('What's the ticker for…', 'find the CIK for…') and states the core action: resolving a name to canonical/official identifiers. It explicitly contrasts itself with 'other tools require as input,' so an agent can distinguish it from sibling lookup tools like entity_profile or validate_claim.

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 gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when NOT to use it, stopping 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?

The description explains the internal behavior: it probes each entity with 'ai_visibility_check' and aggregates results into a ranked list with score, confidence, and signal density. This adds significant context beyond the annotations, which already indicate the tool is read-only, idempotent, and non-destructive.

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, each dense with information. The first sentence states purpose and method; the second provides a use case and return format. No unnecessary words, perfectly front-loaded.

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

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

Given 4 parameters with 100% schema coverage and no output schema, the description fully explains the return format (ranked list with fields). It also references the internal use of a sibling tool and the annotations cover safety. The description is complete for an agent to understand behavior 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 coverage is 100%, so baseline is 3. The description adds meaning: it clarifies the 'entities' array (first is subject, rest competitors) and explains that 'models' includes 'workers-ai' or 'anthropic', with _apiKey required only for 'anthropic'. The 'context' parameter is explained as disambiguation. This 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 specifies the verb 'compare' and the resource 'AI visibility across multiple entities'. It clearly distinguishes from sibling 'ai_visibility_check' (single entity) by emphasizing side-by-side comparison and ranking. Example use case further clarifies its purpose.

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

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

The description explicitly positions the tool for competitive AI-marketing audits and provides an example question. It implies when to use (when comparing multiple entities) but does not explicitly state when not to use or list alternatives. However, the sibling 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?

The description adds significant behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed lists timeouts. Annotations already indicate read-only and idempotent, but the description enriches with real-world runtime 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 concise yet comprehensive, front-loading the key composite check purpose. Every sentence adds value: ecosystem, return fields, delay warning, alternative for other ecosystems. No wasted words, and the structure is easy to scan.

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

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

Given the complexity (composite of multiple sources), full schema coverage, and rich annotations, the description covers all necessary context: return fields, partial failure handling, timing, ecosystem scope. No output schema exists, but the description lists the returned fields explicitly, making it self-contained.

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

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

Schema coverage is 100% for both parameters (package and version). The description adds that version defaults to latest and accepts scoped packages (e.g., @types/node). This provides minimal added value beyond the schema, warranting a baseline score of 3.

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

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

The description clearly states it performs a composite check for adding an npm package, covering license, advisories, version history, bundle size, and tree-shaking. It distinguishes itself from sibling tools by specifying the ecosystem (NPM) and referencing the underlying services (deps.dev, bundlephobia). This specificity ensures the agent understands the tool's unique purpose.

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

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

The description explicitly tells when to use: when an agent asks about package safety, popularity, or size, e.g., 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes limitations (NPM only) and directs to alternatives for other ecosystems (PyPI, Maven, Cargo, Go). This provides clear context for tool selection.

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

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

Annotations already confirm read-only, idempotent, non-destructive behavior. Description adds an example call and mentions returned fields, but does not disclose potential rate limits, pagination, or authentication requirements beyond the optional _apiKey parameter.

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?

One sentence plus a clear example. No extraneous information; every word serves a purpose.

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 the core purpose and return fields despite lacking an output schema. Annotations complete the safety profile. Missing details like pagination limits or result ordering, but adequate for a straightforward search tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. Description lists only 'name' and 'limit' in the example, adding no extra meaning beyond what the schema provides. 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 searches TheGamesDB by title and lists the specific fields returned (platform name, release date, etc.). Differentiates from siblings like get_game and list_genres.

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

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

Provides an example but no explicit guidance on when to use versus alternatives like get_game for detailed single-game data or list_genres for catalog browsing. Usage context is implied rather than stated.

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 idempotent, read-only, non-destructive. Description adds embedding model details (BGE-base-en, cosine, 500-char windows) and a 200K char cap with truncation flagging. No contradiction; valuable extra 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?

Three sentences: first defines core purpose, second provides usage guidance with alternatives, third gives technical details. No wasted words; efficient and information-dense.

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

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

Lacks output schema but description explains return type (passages with offsets and scores) and truncation behavior. Covers parameters and usage context well. Could mention if total count is returned, but not necessary for typical 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%, so baseline is 3. Description adds value with natural-language query examples and clarifies text size limit (200K chars). However, limit parameter details are only in schema. Overall adds meaningful examples beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, returning top-N passages with offsets and scores. It distinguishes from sibling tools like ask_pipeworx_grounded by specifying it works on already-fetched text, making the purpose specific and differentiated.

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

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

Explicit guidance: use when the record is too large for the prompt, saves context. Mentions pairing with ask_pipeworx_grounded for grounding over passages. Implicitly tells when not to use (small records). Clear alternatives provided.

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

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

Discloses beyond annotations: returns subscription ID, requires OAuth (non-anonymous), delivery caps, webhook HMAC signing, and auto-disable behavior. Annotations (idempotentHint=true) are consistent—creation is idempotent. Adds significant behavioral detail.

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 with purpose, types, and delivery details. Efficiently packs essential info with examples and constraints. Slightly verbose due to nested examples but justified by 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?

Fully covers the tool's complexity: multiple types, param formats, delivery options, prerequisites (OAuth, phone verification), limitations (10/day cap), and security (webhook signing). No output schema, but mentions return value. Complete for the tool's scope.

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

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

With 100% schema coverage, the description expands on each parameter with concrete examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'). Adds meaning for 'delivery' including validation rules and webhook signing. Exceeds schema explanations.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verbs and resources. Distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by describing a creation action. Provides concrete examples of supported 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?

Specifies prerequisites (Pipeworx OAuth account, phone verification for SMS) and limitations (10/day cap, webhook auto-disable). Implicitly separates from sibling tools by describing subscription creation vs. listing/removal. Lacks explicit '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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds that the results are drawn from a live catalog, implying dynamic content, and explains the return format (category-bucketed examples with tool+argument shapes). This exceeds what annotations alone provide, but no additional behaviors (e.g., rate limits) are mentioned.

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

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

The description is moderately long but front-loaded with user intent aliases and delivers valuable context. Every sentence adds information; however, the list of categories is somewhat verbose and could be shortened without loss.

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

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

For a tool with one optional parameter and no output schema, the description is fully self-contained. It explains the return content, parameter behavior, and onboarding purpose. The mention of meta-tools provides additional context. No gaps remain.

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

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

Schema coverage is 100% and the description expands on the topic parameter by listing concrete values and explaining the effect of omitting it. This adds significant meaning beyond the schema's brief description.

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

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

The description clearly states the tool returns example questions bucketed by category, explicitly distinguishes it from siblings by positioning it as the first tool to use when onboarding, and names the meta-tools it teaches. The verb (suggest_questions), resource (Pipeworx capabilities), and scope (category-bucketed examples) are highly specific.

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 this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on omitting vs. passing topic. It also refers to sibling tools (meta-tools) as a next step, giving clear when/where-not/alternatives guidance.

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

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

The description adds behavioral context beyond annotations: ownership enforcement, soft deletion, and preservation of historical events. Annotations already indicate readOnlyHint=false and destructiveHint=false, aligning with the description.

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 concise sentences with no redundancy. The core action is front-loaded, and each sentence provides distinct value: action, ownership constraint, and behavioral nuance.

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

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

For a simple single-parameter tool with annotations and no output schema, the description covers all necessary context: what it does, constraints, and data lifecycle. It is complete and self-contained.

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

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

The only parameter 'id' is fully documented in the schema with 100% coverage. The description adds minimal extra meaning by noting it's returned by 'subscribe', but this is not essential. Baseline score 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 action ('Cancel a subscription by id') and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' by emphasizing ownership enforcement and the soft-deletion behavior.

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

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

The description implicitly guides usage by specifying the precondition (ownership) and the effect (deactivation, not deletion). It could be stronger with explicit when-not-to-use or alternatives, but the context is clear.

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

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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, the description adds significant behavioral context: the routing logic, the return verdict vocabulary, the meaning of could_not_verify vs unsupported, citation format, and that it replaces multiple 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?

The description is long but every part earns its place: trigger phrases, routing rules, return details, and critical caller warnings. It's front-loaded with natural-language query examples, and the 'IMPORTANT for callers' section is clearly highlighted. No filler or redundancy.

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

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

Given the tool has only 2 parameters, no output schema, and moderate complexity, the description is remarkably complete: it explains input style, internal routing, output verdicts, evidence citation, error semantics, and alternatives. It fully prepares an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by explaining how tolerance_pct interacts with 'the tolerance implied by the claim wording' and by giving concrete claim examples for the claim parameter. This enriches parameter understanding without replacing 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 starts with a clear verb—validate—and resource (claim), then gives natural-language trigger examples and explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research by noting it replaces 4–6 sequential calls. It clearly distinguishes the tool's purpose from other list/entity/search tools.

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

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

States 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives explicit when-to-use paths: company-financial claims go through SEC EDGAR, any other factual claim routes to the grounded pipeline. It provides strong exclusions and warnings, like 'could_not_verify means the check did not happen... must not be shown as one.'

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