Cftc Cot

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: default model, optional Anthropic probe with BYO key, and the structure of the return value (per-model fields + combined view). 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 (3 sentences), front-loaded with the core purpose, and every sentence adds value. No fluff or repetition.

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

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

The description covers essential aspects: what the tool does, inputs (entity, models, apiKey, context), and output structure. While no output schema is provided, the description compensates with a clear list of return fields. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema (e.g., entity examples, model names, context as a disambiguator). This helps the agent select appropriate values.

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

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

The description uses a specific verb ('probe', 'score') and clearly identifies the resource (LLMs' knowledge about an entity). It distinguishes from sibling tools by focusing on AI visibility scoring, which is unique among the listed tools.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the _apiKey. However, it does not explicitly state when not to use this tool or suggest alternative tools for related but different tasks.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond annotations: it routes internally across thousands of tools, fills arguments automatically, returns stable pipeworx:// citation URIs, and notes it is a single fast call that works on every tier.

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

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

The description is longer than average, but the length is justified for a central default tool that must disambiguate against several siblings. Key guidance is front-loaded with 'PREFER OVER WEB SEARCH', and the rest is a structured set of usage signals, examples, and escalation paths.

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 broad scope, no output schema, and rich annotation context, the description is remarkably complete. It covers what the tool does, when to use it, when not to, what output to expect, and how it differs from close alternatives. An agent has enough information to select and invoke it correctly in almost any factual-query scenario.

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

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

The schema already covers all parameters at 100%, so the baseline applies. The description enhances this by explaining that the free-text parameter is not used directly but is routed to the appropriate specialized tool, with arguments auto-filled, and by providing multiple concrete example queries that clarify expected input.

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

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

Clearly specifies a precise function: routes a natural-language question to the right one of 5,908 tools across vetted sources and returns a cited structural answer. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by framing itself as the default fast entry point.

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

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

The description explicitly tells the agent to prefer this tool over web search for a wide set of factual questions, and names exactly when to step up to ask_pipeworx_grounded or deep_research. It gives concrete trigger phrases and examples, leaving little ambiguity about when to select this tool.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: candidate routing improvements are only live during tests, no candidate is active now, it currently matches ask_pipeworx exactly, and it 'falls back to nothing' — it is a full working router. This meaningfully clarifies the beta/experimental behavior beyond the hint fields.

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 four sentences and every sentence earns its place: beta identity, current status, usage instruction, and no-fallback assurance. The specific details like '5,908 tools' and the date of the last retired candidate are concrete and help set accurate expectations without becoming 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 tool with one required parameter, the description plus schema and annotations covers how to invoke it, when to choose it, and what behavior to expect relative to ask_pipeworx. It notes the response shape is identical to ask_pipeworx, so no output schema is needed. The only slight gap is not explaining how this differs from other ask_pipeworx variants beyond the beta angle.

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

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

Schema description coverage is 100%, with all six string aliases clearly documented. The description only says the tool accepts the same arguments as ask_pipeworx, which adds little semantic value beyond the schema. Baseline 3 is appropriate since the schema already carries the parameter documentation burden.

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

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

The description clearly identifies the tool as 'Beta version of ask_pipeworx' and an 'identical universal router' with the same 5,908 tools, arguments, and response shape. It distinguishes itself from the stable sibling by being the experimental edge, and the title plus 'Use it exactly like ask_pipeworx' communicate the action. It doesn't explicitly define what a universal router does, but the sibling context makes the purpose sufficiently clear.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also mentions that results are compared against the stable router, reinforcing when this variant is relevant. It doesn't mention alternatives like ask_pipeworx_grounded or state when not to use this tool, so it falls just short of full exclusion 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 readOnly and idempotent, but the description goes far beyond: it details the success return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), the refusal structure with specific refusal_reason enum values, and the behavior of using 'ONLY what the tool result contains'. This is rich behavioral disclosure.

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

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

Despite being long, every sentence earns its place: purpose, mechanism, output format, refusal modes, usage criteria, and cost comparison to the sibling. Key facts are front-loaded ('Hallucination-resistant answer mode') and the structure flows logically from purpose to behavior to 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?

With no output schema, the description fully explains the return contract including success and refusal variants, and lists all refusal_reason values. It covers cost, when to use, and how it routes, so an agent has everything needed to select and invoke 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?

The input schema has 100% coverage, documenting the 'question' parameter and its five aliases. The description does not add parameter-level semantics beyond that, which is acceptable because the schema fully handles parameter meaning.

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

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

The description states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads', clearly distinguishing it from ask_pipeworx by adding extraction of the answer only from the tool result. It names the sibling tool 'ask_pipeworx' and describes the routing relationship, so an agent can tell them apart without opening schemas.

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

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

Explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples like financial verdicts and legal claims. It also tells when not to use it: 'prefer ask_pipeworx for casual lookups', and notes the extra LLM call cost as a decisive factor.

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

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

The description extensively discloses behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract (market_match_confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety short-circuits, closed market handling, illiquidity notes, and resolution-rule risk. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds functional context; minimal redundancy. Given the tool's complexity, the length is justified, though it could be slightly tighter.

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

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

Despite no output schema, the description thoroughly covers return shapes, edge cases (low confidence, closed markets, wide spreads), resolver logic, parent events, news fallback, and resolution rules. It is exhaustive for the tool's complexity, leaving no significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the depth parameter default, include_raw's role in controlling summarization, and market input formats with examples. This enriches meaning beyond the schema, justifying a 4.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifies input formats (slug, URL, question text), and outputs an evidence packet with market-vs-model comparison. It distinguishes from sibling tools by detailing its fan-out logic and resolver contract, making its purpose unambiguous.

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

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

The description explicitly gives use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes safety checks (low-confidence resolution, closed markets, wide spreads). While it lacks direct 'when not to use' guidance, the context is clear enough for appropriate invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: source (SEC EDGAR/XBRL for companies, FAERS for drugs), off-calendar fiscal year handling, and sorting by primary metric. No contradictions.

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

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

The description is front-loaded with example queries, then follows a clear structure. It is slightly verbose but every sentence adds value. No redundant information.

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

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

Despite no output schema, the description explains return format (paired data + pipeworx:// citation URIs) and quantifies efficiency ('replaces 8–15 sequential lookups'). For a comparison tool, it is thorough and covers all necessary aspects.

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 substantial meaning: type enum values are explained with what data they pull, and values parameter is clarified with examples for companies (tickers/CIKs) and drugs (names). This goes beyond the schema's minimal descriptions.

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

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

The description starts with common query patterns, then clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by explicitly recommending 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 when-to-use scenarios (comparing entities, 'rank these companies') and prefers this tool over sequential lookups. It also explains the difference between company and drug inputs. Missing explicit when-not scenarios, but the context is strong.

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

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

The main body adds substantial behavioral context beyond the annotations: auth/paid tiers, parallel tool routing, output packet fields, gaps[], contradictions[], citation URIs, semantic excerpting, and latency. However, the later 'This tool is dangerous: ... NOT sandboxed and has NO GUARANTEED OUTPUT FORMATTING. Use with caution. If you don't know what this is, do not call it' directly contradicts the earlier documented findings packet and undermines the readOnly/openWorld/idempotent annotations. This makes the overall description misleading despite its useful core.

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 and front-loads the account requirement, then explains the core behavior and output structure efficiently. However, the final paragraph is redundant, contradictory, and discourages invocation, adding noise without value. It is longer than necessary and contains an internal inconsistency.

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

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

For a complex tool with no output schema, the description covers return fields, auth, depth semantics, latency, and gap handling quite well. But the contradictory 'dangerous / NOT sandboxed / no guaranteed output formatting' passage means an agent cannot fully trust the specification, leaving a serious completeness gap.

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

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

The schema already documents both parameters and provides a detailed description of the depth enum, including hops, gap recovery, contradictions scan, and paid tier. The description repeats much of this and adds the account/sign-in requirement, but it does not add substantial new parameter-level meaning beyond what the schema already covers.

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 defines a grounded multi-source research tool over Pipeworx's structured data sources, explaining facet decomposition, parallel routing, and the findings packet. It distinguishes itself from open-web search and ask_pipeworx. However, the appended 'dangerous / retrieve live internet data / no guaranteed output formatting' sentence muddles that purpose and contradicts the earlier definition, preventing a 5.

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

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

The description is explicit about when to use this tool vs alternatives: use ask_pipeworx when not signed in or for a single lookup; use deep_research for broad, multi-part questions over structured data. It also states the paid-plan requirement for 'thorough' depth, leaving no ambiguity about invocation conditions.

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=true, idempotentHint=true, destructiveHint=false. The description adds that results include full schemas and are ready to call directly, enhancing transparency beyond annotations. No contradictions.

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

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

The description is front-loaded with the core purpose and includes a list of domains and return details. Some redundancy in listing aliases, but overall efficient and well-structured for an AI agent.

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

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

Given the simple parameter structure (single required 'query' with aliases) and no output schema, the description thoroughly explains inputs, aliases, limit, and return contents (names, descriptions, schemas). Usage guidance and domain list provide full context for an agent to decide to use this tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description provides examples and clarifies aliases, but this adds minimal information beyond the schema baseline. No enums or complex types need elaboration.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It differentiates from siblings by specifying it is for discovering tools, not for performing domain-specific tasks, and explicitly lists covered domains.

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

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

Provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It explains when to use it as a discovery entry point, which distinguishes it from sibling tools that perform specific actions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: parallel fan-out, sources_used/sources_failed semantics, soft-fail behavior for the patents API, the expected empty FDA result for companies with only small-molecule drugs, and the resolved:false path for private companies. This goes well beyond the annotations, though it doesn't detail exact response shape or pagination.

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

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

The description is information-dense and front-loaded with example user queries, but it is a very long single paragraph that mixes many distinct concerns: usage examples, source enumeration, soft-fail notes, expected-empty sections, input formats, and private-company behavior. It earns its length through substantive content, but structure would be clearer with bullets or short sections separating 'what it returns' from 'how to call it'.

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

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

For a complex tool with no output schema, the description is remarkably complete: it enumerates all data sources, describes the return sections (cik, company_name, recent_filings, fundamentals, sources_used/failed), explains edge cases (private company, empty FDA section, patents soft-fail), and fully specifies input formats. An agent has enough information to invoke this tool correctly and interpret its results, even without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the accepted value shapes (ticker, zero-padded CIK, company name) and explains that type values are interchangeable, but the schema already documents these semantics. The description adds context about name resolution via SEC EDGAR and private-company behavior, which is useful, but it mostly restates schema content rather than adding entirely new parameter meaning.

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

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

The description opens with concrete user phrasings and a specific verb+resource: 'full cross-source profile of a US public company'. It explicitly names the fan-out sources (SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, H-1B, news, GLEIF) and declares it should be preferred over chaining single-pack lookups. This clearly distinguishes it from sibling tools like resolve_entity and compare_entities.

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

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

The description gives explicit when-to-use guidance: 'Tell me about X / research Acme / brief me on Tesla' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies input flexibility (ticker, CIK, or name), the private-company no-match behavior, and the type parameter's interchangeability, leaving almost no ambiguity about when to select this tool.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description reiterates deletion but adds no new behavioral details (e.g., non-reversibility, error handling). It does not contradict annotations.

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

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

Two sentences, efficient and front-loaded with the action. Every sentence earns its place with purpose, usage, and sibling context. No extraneous text.

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

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

For a simple tool with one parameter, good schema, and annotations, the description fully covers purpose, usage, and pairings. No output schema needed. Complete for confident 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 mentions 'by key' but adds no meaning beyond the schema's 'Memory key to delete.' No additional semantics are provided.

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 'Delete a previously stored memory by key,' providing a specific verb and resource. It also distinguishes from siblings by mentioning pairing with 'remember' and 'recall,' clarifying its unique role.

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

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

The description gives clear when-to-use conditions: 'stale context, task done, or clearing sensitive data.' It also names related tools ('remember' and 'recall') as alternatives for storing or retrieving memories.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, signaling a safe, read-only operation. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and outputs a single text blob ready for site deployment. 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 two sentences plus a concise bullet list of use cases. It is front-loaded with the main action and structured efficiently, with 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 (2 parameters, no output schema, annotations covering safety), the description is complete. It explains what the tool does, how it works, the output format, and provides usage scenarios. An agent has all the information needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description for 'url' adds an example and clarifies it can be a landing page, but the schema already says 'Full URL of the site to summarize'. For 'max_links', both schema and description include default and max. The description provides no additional semantic value beyond the schema.

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

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

The description clearly specifies the verb 'Generate', the object 'llms.txt file', and the resource 'any URL'. It explains the process (fetch, extract, emit) and provides concrete use cases, distinguishing it from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check'.

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

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

The description includes explicit use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. It does not mention alternatives or when not to use it, but the scenarios are sufficiently specific.

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 readOnly, idempotent, not destructive. The description adds value by detailing exact return fields (open interest, long/short/net for three categories, changes) and notes 'Keyless', implying no pagination. 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 concise (two sentences plus a data listing) with no wasted words. It is front-loaded with purpose, and every sentence earns its place by clarifying usage, parameter format, or return content.

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

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

Given the tool's simplicity (single parameter, no output schema), the description adequately covers context. Annotations provide safety profile, and the description explains what data is returned. Minor gap: no mention of potential rate limits or data frequency beyond 'weekly', but overall sufficient.

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

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

Schema coverage is 100% with a clear description of market_name. The description repeats the schema instructions and adds an example, but doesn't provide additional semantic meaning beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns the most recent weekly COT positioning for one futures market. It specifies the resource (COT positioning) and action (retrieve latest), and distinguishes from siblings like report_history by explicitly mentioning 'most recent' and referencing search_markets.

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 when-to-use guidance: for the latest COT data. It instructs to pass exact market names from search_markets with examples. While it doesn't explicitly mention when not to use or list alternatives (e.g., report_history for historical data), the context is sufficient for correct selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and default behavior (active only). Value beyond annotations is limited.

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 purpose, efficient and 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?

Returns fields are listed. With no output schema, description compensates adequately. Could mention pagination, but not essential for this simple list tool.

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

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

Schema description coverage is 100% with clear description for 'include_inactive'. Description does not add extra meaning to parameters.

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 lists the caller's active subscriptions, specifying verb, resource, and scope. 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?

Explicitly advises use for reviewing monitored subscriptions before adding or canceling. Provides clear context, though no explicit when-not cases.

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

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

The description discloses many behavioral traits beyond the sparse annotations: rate-limiting (5/day), no quota impact, claim_token flow for anonymous filing and later status checks, digest-reading cadence, and the instruction not to paste end-user prompts. This is rich, useful 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 long but every sentence carries operational value. It is front-loaded with purpose, then usage, exclusions, mechanics, and limitations. Slightly dense, but structure mirrors importance, so it earns a 4 rather than 5.

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 covers what happens on filing (claim_token, daily digests, roadmap impact), constraints (rate limit, quota), and guidance on what to include. There are no obvious gaps for an agent trying to decide when and how to invoke this tool.

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

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

Schema coverage is 100% for all 4 parameters, so baseline is 3. The description adds significant extra meaning for claim_token (lifecycle of filing without an account and using the token later) and clarifies the overall intent of the type/message fields. Since it improves on the schema, a 4 is justified.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like discover_tools or ask_pipeworx by framing it as the feedback/direct-report channel for issues and praise.

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 guidance is given: use for bugs, feature/data gaps, or praise. It also provides a clear exclusion: only for tools served by this Pipeworx connection, and tells users to file elsewhere for other MCP servers — an explicit 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 declare readOnly, openWorld, idempotent, and non-destructive, so description focuses on additional traits: aggregation source (CF analytics-engine), no PII, and caching behavior (5min-1h). This adds significant value beyond 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?

Two sentences plus a bullet list, all front-loaded with key information. No unnecessary words; every sentence adds value. Ideal length for quick comprehension.

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 what is returned (top tools, packs, volume) and adds caching details. It is complete for a simple read-only tool, though it could mention whether results are paginated or if there is a limit.

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

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

Schema covers 100% of the single parameter with enum and description. The description adds practical advice: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the schema's meaning and guides selection.

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

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

Description clearly states it returns top tools, packs, and call volume over a window, distinguishing it from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists tools). The verb 'returns' and resource 'trending data' are specific and unambiguous.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent demand. It also offers guidance on window selection. While it doesn't explicitly state when not to use it, the advice is sufficient for most scenarios.

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 readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral detail: monotonicity checks, partition-sum checks, semantic anchor for cross-event, partition filter for placeholder slugs, and fill check against live order book. No contradiction.

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

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

The description is well-structured and front-loaded with the main purpose. However, it is somewhat verbose with many technical details (e.g., semantic anchor, partition filter, fill check). Could be slightly condensed while retaining 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?

No output schema exists, but the description details the response structure (opportunities array, partition_check object). It covers all relevant aspects for a complex tool: modes, parameters, algorithms, edge cases, and integration with fill risk. Context signals show 2 params with full coverage, making the description complete.

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

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

Schema coverage is 100% with good parameter descriptions. The tool description adds further context: event mode recommended for specific markets, topic mode for cross-event scanning. It explains what each mode does in detail, significantly enriching the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific use cases, differentiating it from sibling tools like 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 gives explicit guidance: call with no args for trending_scan, pass event for specific market, pass topic for cross-event scan. It provides examples of event slugs and topic questions. It does not explicitly state when not to use each mode, but the guidance is sufficient.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral detail: caching (1h at KV level), three model families, diagnostic output, and edge calculation details. No contradictions with annotations.

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

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

The description is long but efficiently packs technical detail. It is front-loaded with the core purpose, then explains the three segments and parameters. Every sentence adds value, though some agents might find the density overwhelming. The structure is logical and clear.

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

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

Given the complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the output structure (by_segment, diagnostics), the three models, edge fields, knobs, and even why fed candidates are excluded. The agent can fully understand what the tool returns and how to interpret it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the purpose and effect of knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly, including practical guidance on settings. The slippage_pp description discusses trade-offs. This surpasses minimal 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, aimed at 'what should I bet on today'. It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by its unique methodology (Pipeworx data, three segments).

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 is built for discovering betting opportunities without paging through hundreds of markets. It explains tradeable-edge knobs and why fed_candidates are excluded. While it doesn't explicitly state when not to use alternatives, the context strongly implies its specific use case. The sibling list contains related tools, but the description provides enough guidance on its intended usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral detail: 60-day snapshot TTL, decay computed from daily closes (not intraday), gaps when no scan occurred, and that decay numbers use default slippage. 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 dense and front-loaded with the core question. It efficiently conveys complex behavior. Slightly long but every sentence adds value; could be trimmed slightly without losing meaning.

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 no output schema, the description compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]) and includes LIMITS about TTL and decay source. This provides complete context for an agent to understand what data to expect.

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

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

Schema coverage is 100% (both 'days' and 'window' described). The description adds context: default and max for days (14/30, while schema says clamp 2-30), default for window ('1wk' vs schema listing options), and explains their role in lookback and snapshot family.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific trading question. The verb 'answers' with a precise resource (edge time-series) distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage (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 explicitly contrasts a fresh edge vs. a 3-week-old edge, implying when to use this tool for decay analysis. It provides clear context but does not explicitly state when not to use it or mention alternatives, though siblings like polymarket_edges are logically alternative tools for current edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it walks the order book ladder, returns specific fields (e.g., slippage_pp, verdict, thin_legs), and warns about risks like forced directional risk and partial fills. No contradiction with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded key information. While comprehensive, it is slightly verbose; a few sentences could be trimmed without losing meaning, but overall it is 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?

Given no output schema, the description thoroughly details all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk). It also explains the verdict and the dominant loss mode, leaving no ambiguity.

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

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

Schema coverage is 100% with parameter descriptions. The description adds meaning beyond schema: explains the two modes (single-market vs basket), how size_usd is interpreted differently (spend vs target proceeds vs settlement notional), and the default auto-detection of side for basket mode.

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 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). This directly specifies the verb+resource and differentiates it from siblings like polymarket_arbitrage or 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 provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to use it (risk of unhedged directional positions) and the consequences of ignoring it.

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

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

Annotations already mark the tool read-only and idempotent, but the description goes well beyond them: it discloses the token-overlap matching algorithm, the fact that safety fields can be non-empty even on returned pairs, the gross-vs-net fee limitation, skipped comparison categories, and the 'pre-mapped ≠ tradeable' warning. This is exemplary behavioral disclosure for a financial comparison tool.

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 front-loaded with the core purpose and then organized into modes, response format, safety fields, and limitations. Some redundancy exists (e.g., repeated emphasis on both modes), but nearly every sentence adds a distinct operational caveat, so the length is justified for a complex tool with no output schema.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so in detail: leg-by-leg prices, spread.top_spreads_pp, compatibility fields, per-entry flags, skipped counters, temporal alignment semantics, and the fees note. It also documents edge cases like unknown metric_type and unclassified legs, making the tool usable without external reference.

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 semantics: it explains that topic is a pre-mapped shortcut auto-fetching matching events, and that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side. It also clarifies that both modes run the identical matcher, which is valuable beyond the raw schema.

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

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

The description opens with a specific verb and resource: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly differentiates the tool from siblings like polymarket_arbitrage by emphasizing the Kalshi–Polymarket pairing and same-question matching, rather than generic 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 gives strong operational context: two modes, pre-mapped topic shortcuts, explicit ticker/slug overrides, and a caveat that most pre-mapped topics currently return compatibility warnings. It does not explicitly name alternative sibling tools or state 'use X instead', so it stops short of full exclusion 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the listing behavior when key is omitted, scoping details, and pairing with sibling tools. 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 two sentences and contains no fluff. It could be considered slightly verbose with the example list, but remains efficient and 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?

For a simple tool with one parameter and no output schema, the description covers behavior, use cases, scoping, and relational context with siblings. It is fully complete and actionable.

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

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

Schema coverage is 100% for the single parameter 'key'. The description adds meaningful context by clarifying the dual behavior: return a value when key is provided, or list all keys when omitted. This goes beyond the schema's 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 identifies the verb 'retrieve' and the resource 'a value previously saved via remember', and explains the alternative listing behavior when key is omitted. It distinguishes from siblings like 'remember' 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 states when to use the tool ('to look up context the agent stored earlier') and provides concrete use case examples. Also explains scoping and pairing with remember/forget.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that mark_read flags events as read and that subsequent calls exclude them, plus mentions alternative access. No contradictions.

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

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

Four well-structured sentences with no redundant information. The most critical info (what it does, what it returns, key parameters) comes first.

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

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

No output schema, but description clarifies return fields. Covers filtering, mark_read, alternative access. Missing explicit mention of ordering or pagination, but sufficient 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 covers all parameters (100% coverage). Description adds meaning by explaining how mark_read affects subsequent calls and suggests practical use of 'since' and 'type'. Adds value beyond schema.

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

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

The description clearly states it pulls fired events from a subscription feed, specifies the returned fields (source, citation_uri, raw payload), and distinguishes from sibling tools like 'search_markets' or 'ask_pipeworx' by focusing on the feed and polling.

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 context for filtering by type and since, explains mark_read behavior, and mentions alternative access via GET endpoint. However, it does not explicitly state when not to use this tool vs. siblings.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds significant behavioral context: fans out to multiple sources, explains fallback logic, mentions PatentsView sunset, describes input date formats, and output structure with pipeworx:// citation URIs.

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

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

Description is a single paragraph but is efficient and dense with information. It front-loads example queries. Could be slightly more structured (e.g., bullet points) but still concise and readable.

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

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

Despite no output schema, the description explains the return format (changes[] grouped by source, total_changes count, citation URIs). It covers all parameters, data sources, and edge cases (PatentsView sunset). This is highly complete for a read-only aggregator tool.

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

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

Schema coverage is 100%, baseline 3. Description adds value by clarifying allowed values for 'since' with examples ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. This practical guidance goes beyond the schema.

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

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

The description clearly states the tool's purpose as a change feed for a company over a recent time window, using explicit example queries like 'What's new with X' and 'latest on Y'. It distinguishes from sibling tool '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 guidance on when to use (e.g., queries about recent changes) and when not to (use entity_profile for static profiles). It also explains fallback behavior between GDELT and GNews, and mentions that PatentsView is soft-failing until reactivated.

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 idempotentHint=true and destructiveHint=false. Description adds useful behavioral context: memory scoped by identifier, persistence (24-hour for anonymous, persistent for authenticated). Does not contradict annotations.

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

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

Single paragraph, front-loaded with core purpose, no wasted 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 simple tool (2 params, no output schema), description is fully informative: covers scope, persistence, pairing with other tools, and usage scenarios.

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

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

Schema coverage is 100%, so baseline is 3. Description provides example keys (e.g., 'subject_property') and value types, adding some context beyond schema but not significantly.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, specifies key-value storage scoped by identifier, and distinguishes from siblings like 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 tells when to use: 'when you discover something worth carrying forward' and provides examples. It also contrasts with recall and forget, and explains persistence differences between authenticated and anonymous sessions.

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

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

The description adds behavioral details beyond annotations: 'most recent first' (ordering), 'Pass the exact ... from search_markets' (dependency on another tool), and 'Keyless' (authentication status). These details are not captured by the readOnlyHint, idempotentHint, or other annotations, enriching transparency.

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

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

The description consists of four short, purposeful sentences: output description, input requirement, use case, and authentication. No wasted words, and the information is front-loaded with the core functionality. Every sentence earns its place.

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

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

Given two parameters and no output schema, the description covers output type (time series with specific fields), input requirement (market name from sibling), ordering, use case, and authentication. It does not detail error handling or exact output format, but these are not critical for this straightforward tool.

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

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

The schema already has 100% coverage with descriptions for both parameters. The description adds context by reiterating the market_name source (search_markets) and implying the effect of weeks via 'most recent first' and time series nature. This adds some semantic value beyond the schema.

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

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

The description clearly states the tool returns a 'weekly net-position time series' with specific fields (non-commercial net, commercial net, open interest) and ordering (most recent first). It implies a verb like 'retrieves' or 'gets', making the purpose clear. It is distinct from siblings like search_markets, but does not explicitly differentiate from other data retrieval tools.

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

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

The description advises using the exact output from search_markets for the market_name parameter and states the tool is 'useful for trend / sentiment shifts over time.' However, it does not specify when to avoid this tool or mention alternatives among the many sibling tools, limiting its 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 readOnly, openWorld, idempotent, and non-destructive hints, and the description adds substantial behavioral detail beyond that: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous matches returning figi_candidates instead of asserting, unresolved identifiers being explicitly listed, and source labels on every identifier. This gives an agent an accurate model of failure modes and output conventions.

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

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

The description is front-loaded with the core purpose and usage trigger, and nearly every clause carries substantive information. However, the company behavior is packed into an extremely long run-on parenthetical with multiple nested ideas, which hurts scannability and makes the description harder to parse than it needs to be.

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 carries the responsibility of explaining return behavior. It does so thoroughly: return identifiers, ambiguity handling, unresolved fields, source labeling, and degradation behavior are all described. For a 2-parameter read-only resolver with no output schema, nothing essential for correct use 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 coverage is 100%, but the description still adds critical meaning: it expands the company value parameter to accept ISINs, maps ISIN to legal entity via GLEIF, and gives a concrete negative example ('NEW YORK ST DORM AUTH' vs '...revenue bonds') to prevent misuse. These caveats go beyond the schema and materially improve 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 names a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives concrete example phrasings and enumerates supported entity types, making the tool's role as an identifier resolver unmistakable. It also implicitly separates itself from sibling tools like entity_profile or compare_entities by focusing on ID lookup rather than profiles or comparisons.

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

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

The description gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also clarifies how inputs should be phrased for edge cases such as bonds. However, it does not explicitly name alternative tools or state when NOT to use resolve_entity, so the guidance is clear but not fully exhaustive on exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds value by explaining internal behavior: 'Probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized.' 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 action and outcome. Every clause adds value: what, how, use case, return format. Efficient and clear.

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

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

No output schema, but description explains return: 'ranked list with score, confidence, signal density per entity.' Covers purpose, usage, behavioral context, return format. Tool with 4 params (1 required) is 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 description coverage is 100%, so baseline is 3. The description adds semantics not in schema: 'First entry treated as the subject for narrative; rest are competitors.' This provides behavioral context beyond parameter descriptions.

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

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

The description clearly states the tool does 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare/scan), resource (competitor AI presence), and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

Description provides explicit context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' While it doesn't explicitly state when not to use or name alternatives, the usage scenario is clear and well-scoped.

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?

Disclose external calls to deps.dev and bundlephobia, potential 5-30s delay on first measurement, graceful partial failure, and that sources_failed will list failures. Annotations (readOnly, idempotent, openWorld) are complemented, not contradicted.

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 rich but every sentence adds value. Front-loaded with purpose, includes examples, limitations, and return structure. No verbosity.

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 compensates by listing return fields and explaining partial failures. All relevant aspects of this composite, external-calling tool are covered.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minimal extra meaning beyond schema: it mentions default latest version and return fields, but the core parameter semantics are already in the schema.

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

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

The description clearly states the tool's purpose: a composite check across deps.dev and bundlephobia for npm package safety, popularity, and size. It uses specific verbs and resources, distinguishing itself from sibling tools.

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

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

Explicitly tells when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also specifies exclusions: PyPI/Maven/Cargo/Go fall under different 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 cover safety (readOnly, idempotent, non-destructive). Description adds 'Keyless' and clarifies substring matching behavior, providing useful 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?

Two concise sentences with examples. No wasted words; key information is front-loaded.

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

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

For a search tool with no output schema, description explains purpose, input requirements, and downstream usage. Could mention result format or pagination, but sufficient 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 example values, clarifies query is substring match, and explains limit default and max, adding meaningful guidance.

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 finds CFTC COT futures markets by name, with specific verb and resource. It distinguishes from sibling tools by noting it provides inputs needed for latest_report and report_history.

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

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

Explicitly says 'Use this first' to get required names for later tools. Provides examples but does not explicitly state when not to use it or list alternatives beyond the two downstream 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, destructiveHint=false. The description adds beyond this: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap, truncation with flag, and that passages carry character offsets. 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 4 sentences, front-loaded with purpose, then usage, then technical details. Every sentence contributes unique value with no redundancy. It is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description explains return structure: top-N passages, character offsets, similarity scores. It covers limitations (200K chars, truncation), pairing with other tools, and use cases. Complete for a retrieval tool of this complexity.

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

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

Schema coverage is 100% (all 3 parameters described in schema). The description reinforces the text parameter's max length, gives query examples, and mentions the default limit. This adds marginal value beyond the schema, justifying a 4 rather than baseline 3.

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

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

The description clearly states 'Semantic search INSIDE a fetched record.' It uses specific verbs and resources with concrete examples (SEC 10-K, article). It distinguishes from siblings by mentioning 'pairs with ask_pipeworx_grounded' and contrasts with fetching the whole document.

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 the record is too big to cram into the prompt' and explains the benefit of saving context. It also provides an alternative workflow with ask_pipeworx_grounded, giving clear when-to-use and when-not-to-use guidance.

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

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

The description discloses all behavioral traits beyond annotations: mutation (create), idempotency implied, delivery behavior (webhook auto-disable, SMS cap), and OAuth requirement. 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 not overly concise but efficiently packs essential information in three clear paragraphs, front-loaded with purpose. Every sentence earns its place, though it could be slightly shortened.

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 of the tool (multiple types, delivery options), the description covers all necessary context: prerequisites, return value (subscription ID), usage patterns, and delivery behaviors. No output schema needed as return is simple.

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

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

With 100% schema coverage, the description adds significant meaning to each parameter, including detailed type-specific parameters, examples, and delivery channel constraints, far exceeding the schema's brief 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 creates a subscription to a live-data event stream and returns a new subscription ID. It distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description explains prerequisites (Pipeworx OAuth account) and provides examples for each supported type, but does not explicitly state when to use this tool versus alternatives. It offers good context 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it returns category-bucketed example questions, describes categories, and notes it's drawn from a live catalog of thousands of tools. It does not contradict any annotation.

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 detailed but front-loads alternative phrasings. Each sentence adds value, though it could be slightly more concise. The structure is clear and 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 no output schema, the description explains the return format (category-bucketed example questions), covers the single parameter thoroughly, and outlines the use case. It is complete and leaves no major gaps.

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

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

Schema coverage is 100% for the single optional parameter 'topic'. The description adds meaning by listing example topics ('finance', 'pharma', etc.) and stating that omitting it gives a cross-category spread, going beyond the schema's 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 is the onboarding entry point for learning what Pipeworx can do. It lists example questions and specifies it returns category-bucketed example questions with tool+argument shapes, distinguishing it from sibling tools like 'ask_pipeworx'.

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, or to learn how to call the meta-tools'. It also explains calling with no arguments or a topic. However, it does not explicitly state when not to use it, though context implies it's for initial exploration.

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?

Describes deactivation behavior (not deletion) and impact on historical events. Annotations already indicate non-destructive and idempotent; description adds specific behavioral context 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 efficient sentences, front-loaded with 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?

Covers key behavioral aspects, but lacks mention of return value or confirmation, which is minor given simplicity.

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 parameter. Description adds no new 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?

Clearly states verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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 ownership enforcement ('only cancel your own subscriptions'), providing clear context for when to use. Lacks reference to finding subscription IDs via list_subscriptions.

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 and idempotent behavior, but the description adds substantial semantic detail: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source), the SEC EDGAR vs. grounded pipeline split, and the inclusion of a pipeworx:// citation. This goes well 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 fairly long, but every sentence contributes value: trigger phrases, dual-path explanation, verdict definitions, error warning, and efficiency claim. It is well-structured and front-loaded with usage cues. Slightly dense but appropriately sized for a complex tool.

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 explains the returned verdicts, the 'could_not_verify' vs 'unsupported' distinction, the routing logic, and the citation format. It also covers edge cases and the efficiency benefit, making it complete for a tool with this complexity.

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

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

Both parameters are fully described in the schema (100% coverage, including tolerance_pct's semantics and default). The description does not add new parameter-specific meaning beyond the schema's examples and explanations. Baseline 3 is appropriate because the schema already carries the 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 clearly identifies the tool as natural-language claim verification with concrete trigger phrases ('fact check', 'verify the claim that'). It specifies the resource (authoritative sources) and the output (verdict with evidence), and distinguishes itself from siblings by noting it replaces multiple sequential calls.

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 an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for financial vs. other claims. It doesn't explicitly name sibling alternatives to avoid, 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.