dadjokes

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds that calls to Anthropic require a key and pay directly, and returns per-model details including raw_response. This adds useful context beyond annotations, though it does not mention potential variability or failure modes.

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

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

Two sentences, front-loaded with purpose and key details. No redundant language. 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?

Description covers core functionality, default model, API key requirement, return structure, and use cases. Missing details on scoring methodology and confidence calculation, but sufficient for an agent to decide to invoke. With no output schema, the description partially compensates.

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%). Description adds meaning: default model for 'models', clarifying '_apiKey' is only needed for Anthropic, and 'context' is for disambiguation. This provides usage nuance beyond the schema's basic 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 uses specific verb 'probe' and resource 'LLMs for visibility of entity'. It clearly states the tool scores visibility (0-100) per model and mentions default model. Among siblings, this tool distinctively probes multiple LLMs with scoring, differentiating from entity_profile or scan_competitor_ai_presence.

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

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

Description gives use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and notes that Anthropic probing requires BYO API key. However, it does not explicitly state when to avoid this tool or compare to alternatives like scan_competitor_ai_presence.

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, and idempotentHint. The description adds transparency by explaining the tool routes to 3,745 tools across 884 sources, returns structured answers with stable citation URIs. This adds valuable context beyond annotations, though it does not discuss potential latency or cost.

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

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

The description is front-loaded with the key recommendation ('PREFER OVER WEB SEARCH'), then efficiently covers data types, routing behavior, and example queries. While slightly lengthy, every sentence adds value and the structure is logical.

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 that the tool returns a structured answer with citation URIs, but it lacks details on the exact return format (e.g., JSON vs text) and does not address error handling or timeout behavior. More completeness would be beneficial.

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 parameters are well-documented as aliases for the question string. The description provides example questions but does not add additional semantic detail beyond what the schema already offers, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to answer factual questions about current or historical data from authoritative sources, with structured citations. It explicitly says to prefer over web search and lists many specific data types, distinguishing it well from generic web search or other tools.

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

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

The description gives explicit usage guidance: prefer over web search for factual questions, and provides concrete examples of when to use it. However, it does not explicitly compare to sibling tools like 'ask_pipeworx_grounded' or 'deep_research', missing some guidance on when not to use 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond annotations, such as the extra LLM cost, the exact return structure including refusal reasons, and the condition that the tool refuses when data doesn't directly answer. This enriches the agent's understanding without contradiction.

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

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

The description is concise for the amount of information conveyed, with a clear front-loaded purpose and structured breakdown of mechanism, return format, and usage guidance. Every sentence contributes meaningful content, though it could be slightly 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?

Despite lacking an output schema, the description thoroughly specifies the return format including fields like answer, evidence, confidence, source, fetched_at, and refusal_reason with enumerated values. This fully compensates for the absent output schema and makes the tool's behavior predictable.

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% as all six parameters are aliases for 'question' and are documented in the schema. The description does not add additional meaning beyond what the schema already implies; it merely restates the purpose of the tool rather than elaborating on 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?

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, explicitly differentiating it from its sibling 'ask_pipeworx' by noting the extra LLM call and the mechanism of extracting answers only from tool results.

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

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

The description provides explicit guidance on when to use this tool (quoted, cited, or acted-on answers requiring high accuracy) and when not to (prefer 'ask_pipeworx' for casual lookups), with specific use cases like financial verdicts, legal claims, and medical lookups.

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 readOnlyHint true, idempotentHint true, and destructiveHint false. The description adds extensive behavioral details such as fan-out logic, resolver contract, parent_event extraction, news field handling, safety features (short-circuit on low confidence), and market status handling. 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 very long and detailed, which provides high value but sacrifices conciseness. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and front-loaded with purpose, but an AI agent might find it verbose. Some redundancy exists (e.g., repeated explanation of closed markets).

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

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

There is no output schema, so the description must cover return values. It does so thoroughly: result.market fields (bid/ask, liquidity, price change), result.analysis (model probability, edge, kelly), result.evidence (keyed by source), resolver contract (match confidence, alternatives, suggestions), parent_event extraction, news fields with fallback details, and safety features. 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 coverage is 100%. The description adds significant meaning beyond the schema: it explains the market parameter with examples (slug, URL, question text), details the depth parameter (quick vs thorough), and describes the include_raw parameter with context on response size. This goes beyond the schema definitions.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and the action (researching by aggregating data). Among sibling tools, it distinguishes itself from polymarket_arbitrage and polymarket_edges by focusing on a single bet's research.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides clear use cases. However, it does not explicitly state when not to use this tool or mention alternatives among 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?

Annotations confirm read-only, open-world, idempotent, and non-destructive behavior. The description adds detailed behavioral context: it pulls from SEC EDGAR/XBRL or FAERS, handles fiscal year differences, returns sorted results with citation URIs. 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 but well-organized: it starts with example queries, gives usage guidance, then details. It is front-loaded with key information. A few extra words could be trimmed, but it is concise enough.

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 what is returned (paired data, citation URIs, sorted by primary metric). It covers both entity types comprehensively, making the tool's behavior fully understandable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'type' parameter determines data source and what data is pulled, and 'values' is tickers/CIKs for company or drug names. It also provides examples and constraints.

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 side-by-side comparison of 2-5 companies or drugs, with specific examples ('compare X and Y', 'X vs Y'). It distinguishes from siblings by explicitly saying to prefer over sequential single-pack lookups.

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

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

Explicit guidance is given to always prefer this tool over sequential lookups when comparing entities. It also provides examples of queries that trigger it. However, it does not explicitly mention when not to use it or alternative tools.

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

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

Adds value beyond annotations by describing parallelism, gap reporting (never invents), pre-verified facts, structured findings packet, and typical response time. Annotations already indicate read-only, open-world, idempotent, non-destructive, and description aligns 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?

The description is relatively long but front-loaded with key value proposition. Each sentence adds essential information (mechanism, use cases, requirements, output format). Could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (parallel research across many sources), the description covers all critical aspects: functionality, use cases, prerequisites, limitations (gaps, paid plan), and output structure. No output schema exists, but return format is explained adequately.

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

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

Schema coverage is 100%, but description adds meaningful details: explains depth enum values (quick=3, standard=5, thorough=8) and notes that broad/multi-part questions are acceptable for the question parameter. This goes beyond the schema's basic 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 performs multi-source research by decomposing questions into sub-questions and routing them to thousands of sources in parallel. It distinguishes itself from sibling tools like ask_pipeworx by specifying it's for broad or multi-part questions.

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 (broad/multi-part questions) and when not (single lookups should use ask_pipeworx). Also mentions requirements: Pipeworx account and paid plan for thorough depth.

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 behavioral context: returns schemas with curated examples, 'ready to call directly', 'no second schema lookup needed'. This supplements the annotations with useful usage information. 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 relatively long but efficient, with no wasted words. It front-loads the core function and provides examples. Could be slightly trimmed, but overall well-structured.

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

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

Given no output schema, the description explains what is returned (names, descriptions, input schemas with curated examples). It covers the tool's role in an agent's workflow (call first to discover options) and lists example domains. Adequately complete for an agent to understand when and how to use 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 description coverage is 100%, so the schema already documents all 6 parameters, including aliases. The description enumerates use cases and domains but does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Find tools by describing the data or task' and specifies it returns top-N relevant tools with names, descriptions, and schemas. It distinguishes from sibling tools by saying 'Call this FIRST when you have many tools available and want to see the option set', making 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 provides explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for: [list of domains]' and instructs to call this first when many tools are available. It does not explicitly mention when not to use or provide alternative tools, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds specific behavioral details: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, and discloses that USPTO patents part 'soft-fails until reactivated'. 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 comprehensive but slightly verbose. It uses examples and a structured list of return fields. Every sentence adds value, but could be more concise by trimming introductory examples. Still 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 (multiple data sources, caveats), the description is complete. It covers input constraints, output structure, and operational notes (patents soft-fail). No output schema exists, but description details return fields adequately. No gaps identified.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value beyond schema: explains that 'value' can be ticker or zero-padded CIK, that 'type' only supports 'company', and that names require resolve_entity first. This enriches the agent's understanding.

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 clear user intents ('Tell me about X', 'research Acme'), then explicitly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from sibling tools by noting it should be preferred over chaining multiple lookups.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. Provides clear context for tool selection.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds minimal extra but is consistent with annotations. It does not contradict them, and discloses the destructive nature adequately.

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 the primary action, 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?

For a simple tool with one parameter and no output schema, the description fully covers what, when, and how. It is complete and leaves no missing information.

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

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

Schema coverage is 100% with the parameter 'key' having a description 'Memory key to delete.' The description only says 'by key,' adding no new meaning beyond the schema. Baseline score of 3 is appropriate per rules.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb (delete), resource (memory), and method (by key). It also distinguishes from siblings like 'remember' and 'recall' by suggesting pairing, indicating differentiation.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall,' providing clear guidance on alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description explains the process: fetches page, extracts content, emits standard markdown. It adds behavioral context without contradicting annotations.

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

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

The description is a single focused paragraph with front-loaded purpose, efficient language, and no filler. 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?

For a simple tool with two parameters and no output schema, the description covers purpose, usage, behavior, and output format. It could mention network request details or error handling, but it's sufficient for its complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces the purpose of max_links but adds no new semantic details beyond what the schema provides.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the action and output. While it doesn't explicitly distinguish from related siblings like scan_competitor_ai_presence, the unique purpose is evident.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It lacks negative guidance or comparison to alternatives, but the examples are actionable.

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

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

Annotations already declare safe, idempotent, non-destructive behavior. Description adds that it returns 'full joke text', providing return value context. No contradictions.

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

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

Single concise sentence with front-loaded purpose. Every word is necessary; no redundancy or waste.

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

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

Given low complexity (1 parameter, simple get operation) and existence of output schema, the description is sufficiently complete. It covers purpose and return value.

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 'id' parameter is fully documented. Description adds no additional semantic information beyond restating the ID retrieval purpose.

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

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

The description clearly states the verb 'retrieve' and the resource 'specific dad joke by ID', distinguishing it from sibling tools like random_joke (no ID needed) and search_jokes (query-based).

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

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

No explicit guidance on when to use this tool versus alternatives (random_joke, search_jokes). Usage is implied: if you have an ID, use this. Lacks when-not or alternative recommendations.

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, destructiveHint=false, so the tool is safe. The description adds value by specifying the exact fields returned and that it lists active subscriptions by default. No contradictions with annotations.

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

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

Two sentences that front-load the purpose, then list return fields, then provide usage guidance. Every sentence is informative, no wasted words.

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

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

For a simple list tool with only one optional parameter and no output schema, the description adequately explains the return fields, the effect of the parameter, and when to use it. Annotations provide safety 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 coverage is 100%: the parameter include_inactive is described in the schema as 'Include cancelled subscriptions in the response (default false).' The description mentions 'active' subscriptions, which reinforces the default behavior but doesn't add new semantic detail 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 starts with 'List the caller's active subscriptions.' which is a clear verb+resource pair. It distinguishes from sibling tools like subscribe and unsubscribe, and specifies the returned fields.

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 says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides explicit context for when to use the tool, though it doesn't explicitly mention when not to use 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?

All annotations are false, so description carries full burden. It adds key behavioral details: rate-limited to 5 per identifier per day, free (no quota), and team reads digests daily affecting roadmap. No contradiction with annotations.

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

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

Single focused paragraph with front-loaded purpose and actionable guidance. Every sentence adds value; 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 feedback tool with no output schema, description fully covers usage, constraints, and behavioral context. Includes rate limits, quota exemption, and team process, making it self-contained.

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

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

Schema coverage is 100%, but description adds significant meaning: explains enum values in plain language, gives example, advises on message length and specificity, and documents optional context fields.

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

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

The description explicitly states the tool's purpose: sending feedback about bugs, features, data gaps, or praise. It clearly distinguishes from sibling tools by focusing solely on feedback, not on querying data or performing operations.

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

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

Provides explicit when-to-use scenarios for each feedback type (bug, feature/data_gap, praise). Includes guidance on what not to do ('Don't paste the end-user's prompt') and mentions rate limits and quota impact.

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

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

Adds caching details, no PII, source (CF analytics-engine), and aggregation method beyond what annotations cover.

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

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

Efficiently structured with front-loaded purpose and bullet-like use cases, though 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?

Covers return content and caching, but lacks output format details; adequate for a read-only tool.

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

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

Schema coverage is 100% and description adds semantic guidance on window duration (short vs. long), surpassing baseline.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window, with specific use cases that distinguish it from siblings like 'discover_tools'.

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

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

Three explicit use cases are provided, but no direct comparison to sibling tools or when not to use 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 declare readOnlyHint=true, and the description adds substantial behavioral context: failure on empty args, fill check behavior, semantic anchor, partition filter, and response structure. 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 comprehensive but slightly verbose; however, every sentence adds necessary detail. It is well-structured with clear sections for each mode and behavior. Minor trimming could improve conciseness.

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

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

Despite no output schema, the description thoroughly covers the response fields (opportunities, partition_check, fill_check) and explains edge cases (placeholders, low similarity). It also references a sibling tool for custom sizing, making it 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%, and the description adds rich context beyond the schema: example slugs, seed questions, and how each parameter is processed (walks child markets, searches related events).

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 using monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases, and the purpose is distinct 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 states that one of event or topic is required and that calling with no args fails. Provides guidance on when to use each mode (event for specific market, topic for cross-event scanning), and mentions alternatives like polymarket_fill_risk for custom sizing.

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, openWorld, idempotent, and non-destructive. The description goes well beyond by explaining the three model families, caching behavior (1h KV), diagnostics structure, and warnings like 'edge may already be in price'. It also covers edge cases like Fed bets excluded and why. No contradiction with annotations.

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

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

The description is lengthy and dense with technical details, but it is well-structured with clear sections (MODEL_DRIVEN, etc.) and front-loaded with the core purpose. Some sentences could be tightened, but overall it is organized for complex 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 no output schema, the description thoroughly explains the response structure (by_segment, fed, diagnostics) and the fields within each segment (edge_pp_net, kelly_fraction, liquidity, etc.). It covers caveats and filtering logic, making the tool's behavior fully understandable without additional reference.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value by explaining each parameter's purpose, default, and practical guidance (e.g., slippage_pp advice, min_partition_leg_kelly clarification). It clarifies complex interactions like the difference between min_kelly and min_partition_leg_kelly.

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: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with prices. It uses specific verbs ('scan', 'return'), identifies the resource ('Polymarket markets'), and distinguishes from siblings by detailing its unique model families and use of Pipeworx data.

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

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

The description provides context on when to use (e.g., 'what should I bet on today', discovering opportunities without paging) and explains parameter knobs for tuning. However, it lacks explicit comparison to sibling tools like polymarket_arbitrage, so agents may need to infer when to use this vs alternatives.

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

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

Annotations declare read-only and idempotent. Description adds detailed behavioral context: data gaps, TTL bounds, decay computation, and response structure. No contradictions with annotations.

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

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

Description is dense but well-organized: purpose first, then response format, then limits. No redundant sentences, though 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 fully explains the return structure (tracked[], expired[], snapshot_dates[]) and covers limits and data gaps. Complete for a moderate tool with 2 params.

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

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

Schema coverage is 100% with both parameters described. Description reiterates defaults and adds context for window (snapshot family) but does not significantly extend beyond schema. 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 the tool's purpose: edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes from siblings like polymarket_edges by focusing on time-series trends.

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

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

Implied usage context is given (fresh vs old edges), but no explicit guidance on when to use this tool versus alternatives (e.g., polymarket_edges). No 'when not to use' or direct comparison to 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond these, such as explaining basket mode risks (thin_legs, forced_directional_risk) and the consequence of partial fills. 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 appropriately sized for the complexity, uses structured formatting with capitalized key terms and bullet-like lists. It is front-loaded with the main purpose. Could be slightly more concise, but effectively communicates all necessary information without being overly verbose.

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 enumerates output fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict; and for basket: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, etc.). It also explains risks and the behavior of size_usd in basket mode, making it complete for a complex tool.

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

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

Schema coverage is 100%, so the description adds meaning by explaining that market and event are required (one of), clarifying default values for side and size_usd, and describing the interpretation of size_usd in basket mode as 'settlement notional'. These details go 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about the verb and resource, and it differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills leading to unhedged positions). Provides 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?

Description goes far beyond annotations (readOnly, idempotent) to disclose key behaviors: how spreads are calculated (Kalshi - Polymarket), safety fields (compatibility_warning, temporal_alignment, skipped counters), and limitations (rare real spreads). 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 thorough and well-structured (purpose, modes, response, safety), but somewhat lengthy. Each sentence adds value, so it earns a 4 for efficiency while being comprehensive.

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

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

Despite no output schema, description covers response structure (leg-by-leg prices, spread array, top_spreads_pp), all safety fields (compatibility_warning cases, temporal_alignment), and edge cases (matched_pairs=0 scenarios). Fully sufficient 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?

With 100% schema coverage, baseline is 3. Description adds value by listing the 10 topic shortcuts explicitly, explaining override behavior, and providing examples. This is helpful but not essential 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 identifies the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like 'polymarket_arbitrage' by focusing on two-venue spread and specifying modes.

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

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

Explicitly describes two modes ('topic' shortcuts and explicit parameters) with examples. Provides strong guidance on when spreads are meaningful (temporal alignment, bet shape equivalence) and warns that most pre-mapped topics are not yet tradeable, guiding appropriate use.

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

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. Description adds return values but no additional behavioral traits like rate limits or data sources. No contradictions.

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

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

Single sentence, perfectly concise and front-loaded. Every word is necessary.

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?

Tool has zero parameters and an output schema, so description covers essential info: purpose and return structure. Complete for this simple tool.

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

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

No parameters in input schema, so baseline is 4. Description does not need to add parameter info.

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

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

Description clearly states it retrieves a random dad joke and specifies return fields (joke text and ID). However, it does not explicitly distinguish from sibling tools like 'get_joke' or 'search_jokes', which could cause confusion.

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

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

No guidance on when to use this tool versus alternatives. With siblings 'get_joke' and 'search_jokes', users would benefit from context about when randomness is preferred.

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 value by explaining scoping to identifier and pairing with remember/forget, without contradicting annotations.

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

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

Three sentences efficiently convey core function, use case, scoping, and relationships. No redundant or irrelevant information.

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

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

For a tool with one optional parameter, no output schema, and strong annotations, the description fully explains behavior, scoping, and sibling tool relationships. No gaps.

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

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

Schema coverage is 100% for the single 'key' parameter, and its description already states 'omit to list all keys'. The overall description adds contextual meaning about what keys represent (e.g., research notes, addresses), enhancing 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 clearly states the tool retrieves a value saved via 'remember' or lists all keys when omitted. It distinguishes from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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 specific use cases (look up context like ticker, address, notes) and mentions scoping. It implicitly suggests when to use but does not explicitly list when not to, though the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral details beyond annotations: the mark_read parameter affects future calls by flagging events as read, and the feed is also accessible via HTTP. 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 at 4-5 sentences, with the purpose stated upfront. Every sentence adds functional information: return content, filtering options, mark_read effect, and alternative access. No redundancy or unnecessary detail.

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 fields (source, citation_uri, raw payload). It covers the key behaviors (pagination via limit, filtering, mark_read) and even provides an external access point for scripts. This is sufficient for an agent to use the tool correctly without missing critical 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 coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the mark_read behavior ('flag returned events read so the next call only shows newer ones'), which goes beyond the brief schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (fired events from subscription feed) and details what each event carries (source, citation_uri, raw payload). This distinguishes it from siblings like 'list_subscriptions' which lists subscriptions rather than events.

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

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

The description provides clear usage context: filtering by type and/or since, using mark_read to update state, and mentions that polling works fine. It also offers an alternative (same feed via HTTP for scripts/dashboards). However, it does not explicitly state when not to use this tool versus other tools like search or validation tools, which would warrant a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: multiple API calls, fallbacks, soft-fails for USPTO, and return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). 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 thorough and well-structured, starting with example queries, then sources, parameter details, return format, and sibling differentiation. Slightly long but every sentence adds value, so it earns a high score.

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

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

No output schema exists, but the description explains the return format: changes[] grouped by source, total_changes count, and citation URIs. It covers all aspects: purpose, parameters, sources, fallbacks, and sibling differentiation.

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

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

Schema coverage is 100% with descriptions. The description adds more context: acceptable values for since (ISO dates and relative shorthand with examples), value can be ticker or CIK, and recommended use ('Use '30d' or '1m' for typical monitoring').

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 that the tool returns a change feed for a company, fanning out to SEC EDGAR, GDELT→GNews, and USPTO. It distinguishes itself from sibling tool entity_profile which provides static profiles.

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

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

The description provides explicit example queries and explicitly tells when to use entity_profile instead ('Use entity_profile instead when you want the static profile...'). It also explains fallback behavior between GDELT and GNews.

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 false, idempotentHint true, destructiveHint false), description adds key details: key-value pair scoped by identifier, persistence differences for authenticated vs. anonymous sessions, and 24-hour retention for anonymous.

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 with efficient sentences. First sentence clearly states purpose. Every sentence adds value without redundancy.

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

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

For a simple tool with 2 required params and no output schema, description covers purpose, usage, behavioral context, and integration with sibling tools. Complete for the complexity level.

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 examples for key but doesn't add much beyond what the schema already conveys. No additional syntax or constraints.

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

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

Description uses a specific verb 'Save data' and a clear resource 'memory needed later'. It distinguishes from siblings by explicitly mentioning pairing with recall and forget, which are 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 states when to use: 'when you discover something worth carrying forward...' and provides concrete examples. Also mentions alternatives (recall, forget) and scoping details.

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, etc. The description adds that the tool cascades through several endpoints and replaces 2-3 manual lookups, which is useful behavioral context. 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?

Well-structured with examples first, then purpose, then usage guidance, then type details. Every sentence adds value, though slightly longer than necessary. Very 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?

Despite no output schema, the description explains return values for each type in detail (e.g., ticker, CIK, company_name, citation URI). It covers inputs, outputs, and internal behavior, making it complete for a lookup 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 provides 100% description coverage, but the description adds rich detail: for type it says supported values and what each returns (ticker+CIK for company, RxCUI for drug). For value it gives example inputs. This goes beyond the schema's brief explanations.

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

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

The description opens with concrete examples ('What's the ticker for…' / 'find the CIK for…') and explicitly states it resolves names to canonical identifiers. This clearly distinguishes it from sibling tools like compare_entities or entity_profile.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' It does not mention when not to use it, but the positive guidance is strong and clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral details: probes each entity, ranks results, and returns score, confidence, signal density per entity. This supplements the annotations well 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?

The description is concise (three sentences) with no wasted words. It front-loads the core purpose and then specifies output and use case. Every sentence serves a clear purpose.

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

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

Given 4 parameters, no output schema, and rich annotations, the description covers tool purpose, input semantics, and output format (ranked list with fields). It lacks details on output structure (e.g., JSON or array) but is sufficient for the complexity. Output schema absence is compensated by listing fields.

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 4 parameters have descriptions). The description adds significant meaning: 'entities' are brand/business/product names with first as subject; 'models' lists supported values and default; 'context' explains disambiguation role. This goes beyond the schema's basic 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It uses a specific verb (compare) and resource (AI visibility across entities), distinguishing it from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?'. It implies when to use but does not explicitly exclude alternatives or provide when-not-to-use guidance. Still, the context is clear enough for 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?

While annotations already indicate read-only, idempotent, and non-destructive behavior, the description goes further by detailing the fan-out to multiple APIs, the potential 5-30s delay for bundlephobia's first measurement, and how partial failures are handled (sources_failed listed). 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 well-structured, front-loading the core purpose and then detailing sources, return fields, limitations, and failure behavior. Every sentence adds value without redundancy.

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

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

Given no output schema, the description thoroughly lists return fields and structure, covers performance considerations, failure modes, and ecosystem constraints. It provides a complete picture for an agent to use the tool effectively.

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

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

Schema coverage is 100% with clear descriptions for both 'package' and 'version' parameters. The description adds that scoped packages are accepted and version defaults to latest, but these are already in the schema. Thus, no significant additional meaning beyond the schema.

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

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

The description clearly states it's a composite check for npm packages, aggregating data from deps.dev and bundlephobia, and directly addresses common agent queries like 'is X safe / popular / small'. It effectively differentiates from sibling tools by specifying its composite nature and ecosystem scope.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, size, or cost of an npm package. It also mentions what not to use it for (other ecosystems like PyPI, Maven, etc.) and provides graceful degradation behavior.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds only that it returns mock IDs and text. No extra behavioral context like pagination or rate limits.

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 and return format. 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 output schema exists, description mentions return format (IDs and text). For a straightforward search tool, it covers essentials.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions 'by keyword or topic' aligning with query param, but does not elaborate on limit or default 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?

Description clearly states the tool searches dad jokes by keyword/topic and returns mock IDs and text. Distinguishes from sibling tools like get_joke (single) and random_joke (random).

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

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

States when to use (search by keyword/topic). While no explicit exclusions or alternatives, the context of sibling tools provides differentiation. Could be more explicit but sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: truncation at 200K chars with flag, use of BGE-base-en embeddings, cosine similarity, 500-char windows. No contradictions. Missing details on empty results or error handling, but overall strong.

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 moderately long but every sentence adds unique information. Front-loaded with purpose, then usage, then technical details. No redundancy. Could be slightly more concise by omitting model details, but they add transparency.

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 moderate complexity and absence of output schema, the description explains input limits, return types (passages, offsets, scores), use cases, and edge case (truncation). The agent has enough context to invoke correctly and interpret results. Annotations further enhance completeness.

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

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

Schema coverage is 100% (all 3 parameters described in schema). Description adds value with examples for 'query', explains 'text' limit and truncation behavior, and describes the output format (character offsets, similarity scores). Fully compensates for lack of output schema.

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

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

The description clearly states it performs semantic search inside fetched text, returns top-N passages with offsets and similarity scores. It distinguishes from siblings by mentioning 'ask_pipeworx_grounded' and explaining the fetch-then-search pattern.

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 specifies when to use: 'Use when the record is too big to cram into the prompt'. Also explains pairing with 'ask_pipeworx_grounded' and provides a clear workflow: fetch with gateway, then search, then ground. No ambiguity.

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

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

The description discloses account requirements, delivery constraints (SMS cap, webhook auto-disable), and type-specific parameters, adding significant context beyond annotations. No contradiction with annotations.

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

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

The description is lengthy but well-organized with front-loaded purpose. Every sentence provides value, though it could be more structured (e.g., bullet points). No wasted or redundant information.

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

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

Given no output schema, the description covers return value, always-on feed, and optional delivery channels comprehensively. All three parameters are thoroughly explained with examples and constraints.

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?

Despite 100% schema coverage, the description adds detailed explanations for each subscription type's params and delivery sub-params, with examples and constraints, adding meaning beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes 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 requires a Pipeworx OAuth account and explains supported subscription types with examples. It mentions delivery channels and the always-on feed that can be pulled via recent_alerts, giving context for when to use this tool vs alternatives, though it doesn't explicitly list when not to use 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about the return shape (category-bucketed example questions with exact tool+argument shapes) and invocation behavior (no arguments for full spread). 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 user queries and is well-structured, but slightly verbose (multiple lines). Every sentence adds value, but it could be tightened without losing clarity.

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

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

Given the tool's role as an onboarding entry point with no output schema, the description is complete: it explains when to use, what it returns (category-bucketed examples with tool shapes), and parameter behavior. No gaps for an agent to get confused.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: it explains what the optional 'topic' parameter does, lists example values (finance, pharma, etc.), and clarifies behavior when omitted (cross-category spread). This fully compensates for any potential ambiguity.

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 an onboarding entry point that returns category-bucketed example questions about Pipeworx's capabilities. It uses specific verbs ('returns', 'call') and distinguishes from siblings like discover_tools by being the first step for new users.

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

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

The description explicitly advises 'Use this FIRST' when unfamiliar with Pipeworx, and provides guidance on optional topic filtering (omit for full spread, pass specific topic to focus). It also mentions learning how to call meta-tools, implying when to use alternatives.

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

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

Annotations already indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true). The description adds valuable context: the row is deactivated, not deleted, and historical events remain available via 'recent_alerts'. No contradictions with annotations.

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

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

Two sentences with no wasted words. First sentence states the core purpose, second adds critical behavioral nuance. Front-loaded and efficient.

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

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

For a tool with one parameter and no output schema, the description covers purpose, ownership constraint, and the non-destructive nature. It also references 'recent_alerts' for historical events. This is fairly complete, though a note on return value would be beneficial.

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 'id', with its description already present. The description adds that the id is returned by 'subscribe', but this adds marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'cancel' and the resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and the deactivation behavior.

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

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

The description provides a clear usage condition: ownership is enforced (only own subscriptions). It implicitly tells when not to use (if not your subscription) and connects the effect to 'recent_alerts'. However, it does not explicitly list alternatives or when-not-to-use in a broader sense.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data source (SEC EDGAR + XBRL), output format (verdict categories, structured form, citation, delta), and efficiency gain (replaces 4–6 calls). This exceeds what annotations alone provide.

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

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

The description is well-structured, front-loaded with example queries, and each sentence adds distinct information. While thorough, it could be slightly more concise without losing clarity, 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?

Despite lacking an output schema, the description thoroughly explains the return values (verdict types, structured form, citation, delta). It covers input, supported domain, output, and efficiency benefit, making it fully informative for an agent.

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

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

With 100% schema coverage, the description enriches the single parameter 'claim' by providing example phrases and clarifying it accepts natural-language input. The schema only describes it as 'Natural-language factual claim', so the examples add practical meaning.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR + XBRL. It distinguishes from siblings by noting it replaces 4–6 sequential calls, making its utility explicit.

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 guidance on when to use ('whenever the agent needs to check factual correctness') and specifies the supported domain (company-financial claims). However, it does not explicitly state when not to use, e.g., for non-financial or unsupported claim types.

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