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 declare readOnlyHint, openWorldHint, etc., and description adds context about routing to many tools and returning pipeworx:// citation URIs. No contradictions, but description provides useful behavioral details beyond annotations.

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

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

The description is long but well-structured, front-loading the most important information (preference over web search). Each sentence adds value, though some repetition could be trimmed.

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

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

Given the tool's complexity as a routing system, the description covers purpose, usage, examples, and return value format (structured answer with citations). No output schema, but return behavior is sufficiently described.

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

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

Schema coverage is 100% with 6 parameters all documented. Description does not add parameter-specific details beyond what schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool routes factual questions to 5,245 tools across 1369 sources, providing structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research 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?

Explicit guidance to prefer this over web search for most factual questions, with clear examples and conditions for stepping up to grounded or deep research alternatives. Also states it's the default entry point on every tier.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining the beta nature, current state (no active candidate), and that it is a full working router. 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 concise with two sentences, front-loading the key information about identity, purpose, current state, and usage. Every sentence is meaningful 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?

Given the tool's complexity as a beta router with many sub-tools, the description adequately covers its purpose, current state, and usage. It mentions the response shape matches ask_pipeworx, which is sufficient without an output schema. Minor gap: no explicit fallback or error behavior, but acceptable.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description only mentions 'same arguments' without adding extra meaning. Baseline 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with experimental routing improvements. It distinguishes itself from the stable ask_pipeworx sibling by highlighting its experimental edge and current inactive state.

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

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

The description explicitly says to use it like ask_pipeworx when wanting the newest routing. However, it does not explicitly state when not to use it (e.g., for stable behavior), but the context implies it for testing new routing.

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, indicating a safe, non-destructive tool. The description adds valuable behavioral context: it costs an extra LLM call, explains the refusal reasons, and describes the return object shape including evidence, confidence, and source. 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, starting with the core purpose, then usage guidance, then return format and refusal reasons. It is slightly long but every sentence adds value. Could be slightly more concise, but it's well-organized 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?

Given the tool's complexity (many siblings, 6 parameters all aliases, no output schema), the description is comprehensive. It covers purpose, usage context, behavioral details, return format, and refusal reasons. It provides enough information for an agent to use the tool correctly without needing additional context.

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

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

Schema description coverage is 100%: all 6 parameters are documented as aliases for 'question'. The description doesn't add parameter-specific details beyond what the schema provides, but it does mention that the tool fills arguments automatically, which provides context. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It specifies that it extracts answers only from tool results and returns evidence, confidence, and source. It also distinguishes from the sibling ask_pipeworx by noting the extra LLM call cost.

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

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

The description explicitly states when to use the tool: for high-stakes reads where answers will be quoted, cited, or acted on, and the agent must not invent facts (e.g., financial verdicts, legal claims). It also advises preferring ask_pipeworx for casual lookups, providing clear exclusions and an alternative.

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

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

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?

Goes far beyond annotations (readOnly, openWorld, idempotent) by detailing return format: findings packet with verbatim evidence, confidence, source, fetched_at, citations, gaps[], and contradictions[] for deeper depths. Also describes semantic excerpting, hop field, and expected response times.

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

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

While comprehensive, the description is verbose with multiple paragraphs and some repetition (e.g., contradictions mentioned twice). Could be streamlined without losing clarity, but front-loads key info like account requirement and alternative.

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 covers all necessary context: input, behavioral traits, output structure (findings packet with evidence/gaps/contradictions), time expectations, prerequisites, and alternatives. Thoroughly complete for a complex research 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 already describes both parameters (depth enum, question string). Description adds critical context: depth values explained (quick=3 facets, standard=5+gap recovery, thorough=8+iterative, paid), and question as natural language broad/multi-part. 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 performs multi-source research across 1369 structured data sources, decomposing questions into facets. It explicitly distinguishes itself from 'ask_pipeworx' (single lookup, current news) and other 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?

Provides explicit guidance: best for broad/multi-part structured questions; for single lookup or breaking news use ask_pipeworx instead. Also notes account requirements and that 'thorough' depth requires a paid plan.

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 mark read-only, open-world, idempotent, non-destructive. The description adds detail on data sources (SEC, XBRL, USPTO, news, GLEIF), specific return fields, and notes USPTO API sunset. 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?

Densely packed with information, front-loaded with examples. Every sentence adds value, though slightly lengthy and could benefit from bullet points for return fields. Effective overall.

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 documents all return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI). Complete given tool 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%, baseline 3. Description adds meaning: 'type' limited to company, 'value' must be ticker or zero-padded CIK, names not supported. Provides useful context beyond schema.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies, using specific verbs like 'research' and 'brief me'. It distinguishes from siblings like 'compare_entities' and 'resolve_entity' by focusing on holistic overviews.

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 preferring this tool over chaining single-pack lookups for holistic views. Provides clear input guidance: use ticker or CIK, not names, and suggests using 'resolve_entity' if only a name is available.

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?

All annotations are false (readOnlyHint, destructiveHint, etc.). The description adds critical behavioral context: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. 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 informative but slightly long. However, every sentence adds value, and the structure is logical (purpose → usage guidelines → constraints). Could be condensed slightly without losing clarity.

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

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

For a feedback tool with no output schema and moderate complexity, the description is comprehensive. It covers purpose, usage guidelines, rate limits, and input examples, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds extra value by advising to 'describe the issue in terms of Pipeworx tools/packs' and specifying what not to include, which helps the agent formulate correct inputs.

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 for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs ('tell', 'describe') and distinguishes from sibling tools by being the dedicated feedback mechanism.

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 (bug, feature/data_gap, praise) and provides clear exclusions ('don't paste the end-user's prompt'). Also mentions rate limits and that it's free, giving the agent full guidance on appropriate usage.

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

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

Annotations 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 indicate readOnly, idempotent, and non-destructive. The description adds significant behavioral context: it explains the computation methodology, the compatibility_warning field (two cases), temporal alignment, and skipped cross-type counters. This goes well beyond annotations, providing a detailed mental model of the tool's behavior.

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

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

The description is relatively long but well-structured into logical sections: purpose, modes, response, safety fields. Each sentence adds value. Minor redundancy (e.g., 'SAME resolving question' could be implied) but overall efficient.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal alignment, skipped counters). It covers all necessary information for an agent to interpret results correctly, given 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 coverage is 100%, so parameters are well-documented. The description adds semantic clarity by explaining the two modes and providing examples (e.g., 'fed', 'btc'). It goes beyond the schema by clarifying the relationship between topic and explicit parameters, but does not add new parameter details.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and differentiates from sibling tools like polymarket_arbitrage, which focuses on intra-venue 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 explains when to use topic shortcuts vs explicit tickers, and provides safety fields to identify when spreads are not meaningful due to bet shape mismatches or temporal gaps. It warns that real spreads are rarer than the macro-shortcut list suggests, guiding users to interpret results cautiously. Lacks explicit 'use this tool when comparing prices across venues' but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false; description adds that it 'cascades through several lookup endpoints internally' and details returned fields for each type, providing 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?

The description is front-loaded with representative queries, concise while covering all needed details for two entity types, with no redundant sentences.

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

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

Despite lacking an output schema, the description explains return structures fully for both entity types, and annotations cover safety/read-only aspects; the tool's moderate complexity is well-addressed.

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

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

Schema has 100% coverage, but description enriches parameter meaning: for 'value' it lists acceptable forms (ticker, CIK, name for company; brand/generic for drug) and notes auto-disambiguation, which the schema's enum/description does not fully capture.

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 resolves names to canonical identifiers, with specific examples like 'What's the ticker for…' and explicit differentiation from siblings by noting it provides IDs needed by other tools.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID', indicating primary use case and priority; also mentions it replaces multiple manual lookups, guiding 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, 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 already indicate safe read-only, idempotent behavior. The description adds substantial context: automatic routing of financial vs non-financial claims, exact percent-delta math, and the specific verdict categories. This goes beyond annotations, though it omits details like rate limits or authentication requirements.

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 efficiently structured: trigger phrases first, then usage context, then detailed behavior, then return values. Every sentence contributes meaning. It is slightly verbose but not wasteful.

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 fully explains the return structure (verdict, actual value with citation, reasoning). It covers both claim-handling paths and the tolerance mechanism. All necessary behavioral context is provided for a 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% with descriptions for both parameters. The description adds value by explaining tolerance_pct's override behavior and default capping at 5, plus examples of valid claim formats. This enriches understanding beyond the schema.

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

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

The description opens with explicit trigger phrases ('Is it true that…', 'fact check') and clearly defines the tool as natural-language claim verification against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR+XBRL) and other claims (grounded pipeline), and mentions the returned verdict, actual value with citation, and reasoning. This specificity and differentiation from siblings achieves a clear purpose.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. However, it does not explicitly list when not to use or suggest alternative sibling tools for non-factual queries, which prevents a top score.

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