catfacts

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

Annotations already declare the tool as read-only and idempotent. The description adds behavioral details: what the output looks like (per-model fields), that the default model is free, and that Anthropic requires a separate API key. This provides useful transparency beyond the structure.

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

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

Very concise, three sentences total. First sentence states purpose and output. Second explains default and _apiKey. Third lists use cases. 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 tool with no output schema, the description compensates by describing the return structure. It also covers the parameters adequately. With 100% schema coverage and a detailed description, it is contextually 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?

The schema already describes all four parameters fully. The description adds value by explaining the default model and the purpose of _apiKey (BYO key). It also gives examples for entity ('Pipeworx', 'OpenInvoice'). So it adds meaning beyond the schema.

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

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

The description uses a specific verb ('probe') and resource ('LLMs'), defines the output (score 0-100), and lists use cases. It differentiates from sibling tools by focusing on LLM knowledge and visibility scoring.

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 clear use cases and mentions default model and how to include Anthropic, but does not explicitly distinguish from sibling tools or state when not to use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool internally routes queries to one of 3,745 tools and returns results with citation URIs, which is useful context beyond annotations.

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

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

The description is lengthy and contains some redundancy (e.g., repeating 'PREFER OVER WEB SEARCH' and listing use cases twice). While information-rich, it could be more concise.

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

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

Given the tool's complexity (no output schema, many sources), the description sets reasonable expectations: it returns structured answers with citations and covers a broad range of factual queries. It could be improved by hinting at failure modes or response time.

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 aliases documented. The description provides concrete example queries (e.g., 'Any recent SEC filings for $NVDA?') that illustrate parameter usage, adding value beyond the schema alone.

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

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

The description clearly states that the tool routes natural language questions to a large set of verified sources and returns structured answers with citations. It distinguishes itself from web search and implicitly from sibling tools by emphasizing authority and structure.

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 to prefer this tool over web search for factual questions and provides extensive examples of appropriate queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). It also lists trigger phrases like 'what is', 'look up', 'find'.

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 context beyond annotations: discloses extra LLM call cost, details output structure (answer, evidence, confidence, source, fetched_at, refusal_reason), and lists possible refusal reasons, all aligning with readOnlyHint and idempotentHint.

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

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

The description is well-structured and front-loaded, containing only essential information, though slightly dense for quick consumption; earns a 4.

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

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

With no output schema, the description fully covers the return format and error handling, providing complete contextual information for the agent.

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

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

Schema coverage is 100% with clear aliases for 'question'; the description does not add further semantic value beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as 'Hallucination-resistant answer mode for high-stakes reads' and explains the grounded extraction process, distinguishing it from the sibling ask_pipeworx tool.

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

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

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and advises preferring ask_pipeworx for casual lookups, providing clear usage boundaries.

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 provides extensive behavioral details far beyond annotations. It covers the resolver contract (match confidence, alternatives, suggestions), parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence matches, closed market handling, wide spread warnings, and resolution-rule risk. All annotations (readOnlyHint, etc.) are consistent, and no contradictions exist.

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 excessively long (several paragraphs with many examples and edge cases). While thorough, it lacks conciseness. Important information is front-loaded (purpose and input), but the depth of detail makes it hard for an AI agent to quickly parse. A more condensed version would improve usability.

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

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

Given the complexity of the tool (3 parameters, no output schema), the description is remarkably complete. It fully explains the response shape (market, analysis, evidence), resolver contract, parent event extraction, news fields, safety measures, and resolution-rule risk. No output schema exists, so the description must cover return values, and it does so exhaustively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining how each parameter affects behavior: e.g., 'market' can be slug, URL, or question text; 'depth' enum with quick vs thorough; 'include_raw' with file size context. 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's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and what it produces (evidence packet + market-vs-model comparison). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, leaving some ambiguity in tool selection.

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 examples (e.g., 'should I bet on X') and lists specific classifiers and fan-out patterns, which helps the agent know when to use it. However, it lacks explicit guidance on when not to use this tool or what alternatives to consider (e.g., if the user wants edge detection across multiple markets).

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=true, idempotentHint=true, destructiveHint=false. Description adds specific behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs. No contradictions, and enriches 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 detailed but not overly verbose; front-loaded with query examples. However, it could be slightly more concise by removing redundant phrases like '— side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' already implied by title.

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 2 params and no output schema, description explains what data is returned (revenue, net income, etc.), that results are sorted, and includes citation URIs. It also notes it replaces 8–15 sequential lookups, providing sufficient context for correct invocation.

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

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

Schema coverage is 100% with basic descriptions. Description adds meaningful context: for 'type' clarifies data sources (SEC filings vs FAERS), for 'values' provides examples and explains tickers/CIKs vs drug names. This goes beyond schema, though schema already covers the basics.

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 compares 2–5 companies or drugs in one call, with specific verb 'side-by-side comparison' and examples like 'X vs Y'. It distinguishes from sibling tools (e.g., entity_profile, get_fact) which do single-entity lookups, 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', gives example queries, and covers both company and drug types. This provides clear when-to-use guidance and 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 read-only, open-world, idempotent. Description adds all the behavioral details: never invents, provides verbatim evidence, gaps[] for unanswered, citations, parallel routing to 3,745 tools, expected latency 15-60s.

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

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

The description is fairly long but front-loaded with the key capability. Every sentence serves a purpose, though some details could be slightly more compressed.

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

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

Given the complexity of the tool and no output schema, the description fully covers behavior, prerequisites, expected outputs, and limitations, leaving no critical gaps.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description adds value by explaining the numeric meaning of depth options (quick=3, standard=5, thorough=8) and that question can be broad/multi-part.

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

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

The description specifies a clear verb ('research') and resource ('multi-source grounded research'), and distinguishes from sibling 'ask_pipeworx' by noting it's for broad/multi-part questions vs single lookups.

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

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

Explicitly states when to use (broad/multi-part questions) and when not (single lookups, recommending ask_pipeworx). Also mentions prerequisites: 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 and idempotentHint=true. Description adds valuable operational details: returns top-N relevant tools with full schemas and curated examples, no second lookup needed.

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 fairly concise given the complexity, with key points front-loaded. Every sentence adds value, though could slightly tighten the domain list.

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

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

Given no output schema, the description adequately explains what the tool returns (names, descriptions, full schemas). Covers intended use and output format comprehensively.

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

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

Schema coverage is 100% with parameter descriptions. Description mentions aliases and natural language usage, but adds limited additional meaning beyond the schema's existing 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?

Explicitly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.). Distinguishes itself from siblings by positioning as the first call to explore the tool set.

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 clear when-to-use: 'Call this FIRST when you have many tools and want to see the option set (not just one answer).' Implicitly advises against using for direct answers.

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 safe, read-only, idempotent behavior. Description adds significant detail: fans out across multiple sources, returns specific fields, notes patent sunset soft-fail, and describes return structure including URIs and sorting.

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 with information but well-structured: examples first, then behavior, then return details. Slightly long but every sentence adds value. Could be slightly more concise.

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

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

With no output schema, the description thoroughly explains return values: CIK, company name, filings with URIs, fundamentals (sorted by period_end DESC), patents (with sunset note), news, LEI. Completeness is excellent.

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

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

Schema covers 100% of parameters but description adds practical examples (AAPL, zero-padded CIK) and caveats (names not supported). Clarifies that only 'company' type is supported currently.

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

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

The description clearly states the tool provides a full cross-source profile of US public companies with concrete examples. It distinguishes itself from sibling tool 'resolve_entity' by specifying that names are not supported and that resolver should be used first.

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: 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also states when not to use (if only have a name, use resolve_entity instead).

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

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

Annotations already indicate destructiveHint=true, so the description's 'Delete' aligns. The description adds context about clearing sensitive data but does not elaborate on side effects like permanence or confirmation, which are partially covered by 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 short, front-loaded sentences with zero waste. Every sentence serves a purpose: what it does, when to use it, and related tools.

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 purpose, usage context, and related tools. Annotations fill the remaining behavioral details.

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

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

The input schema has 100% coverage with a clear description for the 'key' parameter. The description merely restates 'by key' without adding new semantic value beyond the schema.

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

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

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

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

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

The description lists clear use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with 'remember' and 'recall', but does not explicitly state 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 destructiveHint=false, indicating safe read-only operation. The description adds value by explaining the extraction process (fetches page, extracts title/description/key links) and the output format (standard llms.txt markdown). This goes beyond annotations without contradiction.

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

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

The description is a single, well-structured paragraph that front-loads the core action and output. Every sentence adds value, and there is no extraneous information. It is concise 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?

The description provides sufficient context for a simple tool with 2 params and comprehensive annotations. It explains the output format and extraction process, covering the main aspects. Lacks explicit error handling details but is adequate for the tool's simplicity.

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

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

Schema coverage is 100%, so both parameters (url, max_links) are fully documented in the schema. The description does not add additional meaning beyond restating the output format. Baseline 3 is appropriate as the description adds no extra parameter insight.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and target (any URL). It distinguishes itself from siblings like ai_visibility_check by focusing on generating the file rather than analyzing AI presence.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor visibility. While it doesn't explicitly state when not to use or name alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already declare idempotent, read-only, non-destructive behavior. The description adds that the fact is random, which is key behavioral context not captured in annotations.

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

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

Two concise sentences, front-loaded with purpose, and no extraneous words.

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

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

With no parameters and an output schema present, the description sufficiently covers what the tool does and its scope.

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

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

No parameters exist, so baseline 4 applies. The description does not need to add parameter info, and it doesn't.

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 gets a random cat fact and returns its text and character length. It distinguishes itself from sibling get_facts by specifying single vs. multiple facts.

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 to use get_facts for multiple facts, providing clear guidance on when to use alternatives. No other 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?

Annotations already convey readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the return format: 'Returns array of fact texts with character lengths', which is behavioral detail beyond what annotations provide. No contradictions.

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

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

The description is two short sentences, each serving a clear purpose: stating the action and usage/output. It is front-loaded with the primary verb and resource, with zero redundancy or filler.

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

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

Given the tool's simplicity (one optional parameter, clear output described), the combination of annotations, schema, and description fully covers what the agent needs to know. The description explicitly mentions the return structure, 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% for the single parameter 'limit', which already describes its type and default. The description only adds an example value and confirms the default, offering minimal extra semantic meaning. 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 'Get' and the resource 'multiple random cat facts at once', which effectively distinguishes it from the sibling tool 'get_fact' (singular) by emphasizing multiplicity. However, it does not explicitly name the sibling or contrast 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 a usage hint by saying 'Specify count (e.g., 5)', implying the typical way to invoke the tool. But it offers no guidance on when to use this tool versus the sibling 'get_fact', nor any exclusion criteria. This is adequate but could be more explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds return field details but no further behavioral context like auth requirements or pagination. Adequate but not enhanced beyond annotations.

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

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

Two concise sentences with no unnecessary words. Front-loaded with the main action and return data.

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 full schema coverage and an output schema, the description is inconsistent—claiming a search-by-name feature not present in the input schema—leaving the tool's actual capabilities unclear.

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

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

The description mentions 'search by name' but the input schema only includes a `limit` parameter with no name parameter. This contradiction misleads the agent about available 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 lists or searches cat breeds by name and specifies the return fields, making it distinct from sibling tools like 'get_fact' or 'get_facts'.

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 vs alternatives like 'get_fact' or other siblings. No explicit conditions or exclusions provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by listing returned fields and default behavior (only active subscriptions). No contradictions.

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

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

Two sentences: first states purpose and output, second gives usage guidance. No wasted words, front-loaded with key 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 explicitly lists return fields. Parameter is well-covered. Lacks pagination info but acceptable for a simple list tool with good annotations.

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

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

The sole parameter 'include_inactive' is fully described in the schema with description and default. The tool description mentions 'active subscriptions' but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields. It distinguishes from siblings 'subscribe' and 'unsubscribe' by mentioning usage for review before adding or to find an id to cancel.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It doesn't explicitly state when not to use, 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?

Discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota. Annotations are neutral; description adds behavioral context beyond annotations.

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

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

Concise paragraph with no wasted words. Front-loaded with purpose, then usage, then constraints. 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?

Covers all necessary aspects: what, when, how, constraints. Nested object and enum parameters are adequately described. No output schema needed for a feedback 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 baseline is 3. Description adds value by explaining the meaning of each enum value and advising against pasting prompts, but schema already has good 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 it's for sending feedback about Pipeworx tools: bugs, features, data gaps, praise. It distinguishes from sibling tools by being the only feedback tool, and uses specific verbs like 'tell' and 'use when'.

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 the tool: for bugs, missing features, data gaps, or praise. Also provides what not to do: 'don't paste the end-user's prompt.' No alternative tool exists among siblings for feedback.

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 valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h depending on window). No contradictions.

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

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

The description is concise with 4 well-structured sentences, each serving a purpose. The bullet-like structure (1), (2), (3) aids readability. No unnecessary words.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description is complete. It covers return value, use cases, data source, caching, and privacy. No missing 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% with the 'window' parameter described via enum. The description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds context beyond the enum values.

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

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

The description clearly states the tool's purpose: returning top tools, packs, and call volume over a window. It uses specific verbs like 'returns' and 'discovering', and is easily distinguished from siblings like 'discover_tools' which likely have different scopes.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment). It does not explicitly say when not to use, but the use cases are sufficiently clear for an AI agent.

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 substantial behavioral details: failure conditions (no args, low similarity, placeholders), internal logic (monotonicity checks, partition sum), and the fill check that prevents trading when overround is not in the book. 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 detailed and packed with information, but it is lengthy. Every sentence adds value, but the structure could be improved (e.g., using bullet points for modes or features). It is not wasteful, but slightly verbose for a tool description.

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

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

Given the tool's complexity (two modes, algorithms, edge cases) and lack of output schema, the description is remarkably complete. It explains response fields, fill check, similarity thresholds, partition filters, and even points to an alternative tool for custom sizing.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning beyond the schema: recommends event mode, explains that topic is for cross-event scanning, provides examples of acceptable inputs (slugs, URLs, seed questions), and describes how each parameter affects behavior and results.

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

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

The description clearly identifies the tool's purpose as finding arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies two modes (event and topic) and distinguishes them from sibling tools like polymarket_fill_risk and polymarket_edges by mentioning alternative use cases.

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 each mode (event for specific markets, topic for cross-event scanning) and warns that calling with no arguments fails. It also references polymarket_fill_risk as an alternative for custom sizing, giving clear context and exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral details: model families, response segments, caching (1h), knobs, and diagnostics. 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 a dense paragraph with technical details mixed together. It could benefit from structured sections or bullet points. It is not concise; the length is justified by content but could be better organized.

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

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

Given the tool's complexity (9 parameters, three response segments, diagnostics), the description is very complete. It explains the models, response top-level, knobs, and even why segments might be empty. No output schema exists, so the description compensates well.

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 detailed descriptions for all 9 parameters. The description adds some extra context (e.g., min_kelly skips small opportunities) but does not significantly go beyond schema.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price. The verb 'scan' and resource 'top Polymarket markets' are specific, and it distinguishes from sibling tools like polymarket_arbitrage by focusing on 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 explicitly says it's built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides clear context for use but does not explicitly state when not to use or compare 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?

Beyond annotations (readOnly, idempotent), the description discloses critical behavioral details: 60-day snapshot TTL, gaps when no scan occurred, response structure (tracked, expired, snapshot_dates), and data source limitations (daily closes, not intraday). 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 information-dense but lengthy, covering response structure and limits in one block. While well-organized with front-loaded purpose, the verbosity might hinder quick scanning. Could be more concise.

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

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

Without an output schema, the description fully explains the return values (tracked, expired, snapshot_dates with fields) and all relevant limitations (TTL, gaps, data frequency). 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 covers both parameters fully (100%). The description adds value by reiterating defaults, specifying max lookback (30 days), and listing snapshot families, providing slightly more context than the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, using specific verb and resource. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current values, answering 'how long has this edge existed and is it shrinking?'.

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 context implies usage for evaluating edge age before trading by contrasting fresh vs old wide edges. However, it does not explicitly name alternatives or state when not to use this tool, missing the opportunity to provide clear guidelines.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds substantial behavioral detail: walks the ladder, returns verdict (clean/degraded/cannot_fill), and warns about basket fill risks (stranded legs). 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?

Description is comprehensive but lengthy. However, all sentences provide value, and it is well-structured with clear sections for single-market and basket modes. Minor deduction for verbosity, but highly informative.

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, yet description enumerates all return fields for both modes: top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket. Very complete.

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

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

Schema coverage is 100% with all 4 parameters described. Description adds significant meaning: explains size_usd differences between single-market (USD to spend/proceeds) and basket (settlement notional), and side auto-detection for basket. Goes well beyond schema basics.

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 performs a realizable-vs-theoretical edge check using live CLOB order-book depth. It distinguishes two modes (single-market and basket) and lists specific return fields. 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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why: theoretical overround not capturable on thin books and partial basket fills convert arb into unhedged directional position.

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 substantial details beyond annotations: compatibility_warning behavior, temporal alignment, skipped type counters, and explanations of non-equivalent bet shapes. Annotations confirm read-only and idempotent nature, with no contradictions.

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

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

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Dense but every sentence adds value; could be slightly trimmed without losing precision.

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

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

Covers purpose, modes, response fields, safety warnings, and limitations thoroughly. No output schema, so description compensates by detailing return fields and edge cases. Complete for a complex cross-venue tool.

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

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

Schema coverage is 100% with descriptions. Tool description adds meaning by explaining mode switching (topic vs explicit), the list of valid topics, and override behavior. Adds relational context without redundancy.

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

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

Description clearly identifies the tool as a cross-venue spread calculator between Kalshi and Polymarket. It specifies two operation modes (topic shortcuts and explicit tickers) and distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue 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?

Provides context on when to use (comparing spreads) and warns that most pre-mapped topics return compatibility_warning. However, lacks explicit exclusions or direct comparisons to alternatives, though sibling names give implicit differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds transparency about scoping (anonymous IP, key hash, account ID) and pairing with remember/forget, which complements annotations without contradiction.

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

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

Four concise sentences, front-loaded with purpose. Every sentence contributes meaningful information 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 tool with one optional parameter and no output schema, the description covers purpose, usage modes, scope, and pairing with siblings. It is fully 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%, so baseline is 3. The description adds value by providing examples and clarifying the dual behavior (omit key to list all).

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 saved values or lists all keys, using specific verbs and resource. It distinguishes two modes (value lookup vs. key listing) and mentions sibling tools for context.

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

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

Provides explicit when-to-use examples (e.g., user's target ticker, address, research notes) and context about scoping. Does not explicitly state when not to use, but the use cases are 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 and idempotentHint. The description adds that mark_read flags events as read and unread_only filters, and that polling is safe. No contradictions. Adds useful behavioral context beyond annotations.

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

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

Single paragraph with dense information. Front-loaded purpose, then lists qualities and filters. Every sentence provides value. Could be slightly improved with bullet points but remains concise.

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

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

No output schema, so description explains return fields (source, citation_uri, payload). Covers filters and side effects (mark_read). Does not explain limit parameter behavior, but schema handles that. Mostly complete for a read-only tool with 5 parameters.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). The description adds extra meaning: examples for type ('sec_8k'), ISO timestamp format for since, and clarifies mark_read effect ('flag returned events read so the next call only shows newer ones').

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 'Pull fired events from your subscription feed' and lists specific return fields (source, citation_uri, raw event payload). It distinguishes from sibling tools like list_subscriptions by focusing on events rather than subscription definitions.

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 clear context for filtering (type, since) and the mark_read behavior. Mentions polling works fine and points to an alternative REST endpoint for scripts/dashboards. Does not explicitly compare to siblings but usage is well implied.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: fans out to multiple sources, fallback mechanism, USPTO soft-fail, and return structure (changes grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is relatively long but every sentence is informative. It front-loads common queries and uses examples. Could be slightly more concise, but it is well-structured and easy to parse.

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

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

Given the tool's complexity (multiple sources, fallback, no output schema), the description covers sources, fallback, and return structure. However, it lacks details on pagination, limits, or the exact fields in each change item. Slight gap in 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 description coverage is 100%, so parameters are documented. The description adds extra value: examples for 'since' (relative shorthand like '7d', '30d', '3m', '1y'), recommendation for typical monitoring ('30d' or '1m'), and clarification that 'value' accepts ticker or CIK. This goes beyond the schema.

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

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

The description clearly states it provides a change feed for a company in the last N days/weeks/months, lists specific sources (SEC EDGAR, GDELT→GNews, USPTO), and explicitly distinguishes from sibling tool entity_profile for static profiles. The purpose is specific and well-defined.

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 query patterns ('What's new with X', 'latest on Y'), provides a direct alternative ('Use entity_profile instead when you want the static profile'), and explains fallback behavior (GDELT preferred, GNews when rate-limited). This offers clear guidance on when and how to use the tool.

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

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

Description adds persistence details: authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already provide idempotentHint=true and destructiveHint=false, but description adds context about scoping and duration.

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

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

Four sentences with clear structure: purpose, usage, behavior, and pairing with sibling tools. No fluff, front-loaded.

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

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

For a simple 2-param tool with no output schema, the description covers purpose, usage, behavior, and references siblings. No gaps.

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

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

Schema has 100% coverage with clear descriptions for key and value. Description provides real-world examples (e.g., 'resolved ticker') but adds minimal extra meaning beyond schema.

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

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

The description clearly states the tool saves data for later reuse, with specific examples like resolved ticker or user preference. It distinguishes from sibling tools 'recall' and 'forget'.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. References sibling tools 'recall' and 'forget' for retrieval and deletion.

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 that each call cascades through several lookup endpoints internally and replaces 2-3 manual lookups, providing useful behavioral context beyond annotations.

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

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

The description is a dense single paragraph with examples and details, but every sentence adds value. It could be slightly more structured with bullet points for types, but it remains clear and front-loaded with the core 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?

Despite no output schema, the description provides comprehensive information: input format, supported types, return details, internal cascading behavior, and citations. Given the tool's complexity (multiple entity types and lookups), the description fully supports an AI agent's understanding and correct invocation.

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

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

Input schema has 100% description coverage for both parameters. The description enriches by specifying return values per type (e.g., for company: ticker + CIK + company_name + citation URI; for drug: RxCUI + ingredient + brand + citation), 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 explicitly states the tool resolves user-spoken names to canonical identifiers, provides example queries, and distinguishes from sibling tools by noting it replaces 2-3 manual lookups. It uses a specific verb (resolve) and resource (name to identifier), fulfilling the highest clarity criteria.

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

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

The description clearly states 'Use FIRST whenever you have a name but need an ID.' It also details supported types (company, drug) with examples. However, it does not explicitly mention when not to use it or provide alternatives among siblings, which would elevate to 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?

Adds value beyond annotations: explains it probes each entity with ai_visibility_check, ranks by score, and returns rank list with score, confidence, signal density. Annotations already declare safe, non-destructive, idempotent, so description enriches behavioral context.

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

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

Three sentences, no filler. Front-loaded with purpose, then method, then example. 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?

Covers purpose, usage scenario, behavioral details, parameter semantics, and return value structure. No output schema needed; description sufficiently describes output. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds key semantic: first entity treated as 'subject' for narrative, rest as competitors. Also explains context param disambiguates common names. Adds meaningful usage guidance.

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

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

Clearly states the verb 'Compare' and resource 'AI visibility' for multiple entities. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying side-by-side comparison and ranking.

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?

Gives explicit use case 'competitive AI-marketing audits' with an example question. Implies when to use (multi-entity comparison) vs single check. Could add when not to use, but context is clear.

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

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

Annotations already provide safety and idempotency hints. Description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed will list timeouts, and describes return structure (summary block, advisories, links, alternatives). This goes well beyond annotations.

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

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

Description is thorough but not overly verbose. Every sentence adds useful information, though slightly long. Front-loaded with core 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?

Despite no output schema, the description fully explains return content, partial failure behavior, and constraints. It is complete for a read-only composite tool with well-annotated safety and idempotency.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds clarification: scoped packages are accepted, version defaults to latest when omitted. This adds value beyond schema.

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

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

The description clearly states the tool performs a composite check for npm packages, answering 'should I add this npm package'. It distinguishes from siblings by specifying NPM ecosystem and combining two data sources (deps.dev and bundlephobia).

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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small"' and notes limitations: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.' This helps avoid misuse.

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, non-destructive. Description adds detailed behavioral context: embedding model (BGE-base-en), windowing strategy (500-char overlapping windows), character cap (200K chars with truncation and flag), and returned data (character offsets, similarity scores). 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?

Five well-structured sentences, no wasted words. Front-loaded with core purpose and usage, then covers details and limitations efficiently.

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

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

Despite no output schema, description fully explains return format (top-N passages with offsets and similarity scores) and internal mechanics (embeddings, windows, cap). Pairs with sibling tool for grounding. Complete for a search tool with rich annotations.

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

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

Schema already covers all 3 parameters with descriptions, so baseline is 3. Description adds value by providing examples for query ('supply-chain risk', 'fiscal year 2024 revenue') and explaining the text parameter's max size and purpose, going beyond the schema.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K body, article, long tool result) and explicitly distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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: 'Use when the record is too big to cram into the prompt' and describes how it saves context by returning only relevant passages. Also provides complementary tool (ask_pipeworx_grounded) for grounding over passages.

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 behavioral traits beyond annotations, such as the need for OAuth (not anonymous/BYO), SMS daily cap (10/day), webhook auto-disable after 10 failures, and that delivery channels are optional on top of an always-on feed. This supplements the annotations well.

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

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

The description is a single dense paragraph but front-loads the main purpose and prerequisites. It packs substantial information without being overly verbose, though structuring with bullet points could improve readability.

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

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

Given the complexity of the subscription tool, no output schema, and full schema coverage, the description covers all necessary aspects: types, parameters, delivery options, and behavioral constraints. It feels complete for an agent to understand and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning by providing concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic) and detailed delivery channel constraints (email verification, SMS cap, webhook HMAC signing).

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. This distinguishes it from sibling tools 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 provides clear context on when to use the tool, including prerequisites (Pipeworx OAuth account) and supported subscription types with delivery channels. It does not explicitly compare to alternatives but the usage context is well-defined.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that results are drawn from a live tool catalog and shows sample categories. No contradiction, and adds meaningful behavioral context beyond annotations.

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

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

Description is somewhat verbose, starting with a list of user questions. While informative, some redundancy exists. Front-loaded with purpose but could be tighter. Still clear and 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, description adequately explains return type (categorized examples with tool+argument shapes) and covers usage scenarios. Could detail response format more but sufficient for effective use.

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

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

Schema coverage is 100% with a detailed parameter description. Description adds minimal extra value by restating examples and clarifying default behavior (cross-category spread). Baseline 3 is appropriate.

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

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

Description clearly states the tool returns category-bucketed example questions with tool+argument shapes, serving as onboarding entry point. Distinguishes from sibling tools like ask_pipeworx and discover_tools by positioning itself as a 'first use' guide.

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 to use this tool first when unsure about Pipeworx capabilities, and to learn how to call meta-tools. Provides guidance on calling with or without the topic argument. Does not explicitly contrast with all alternatives like discover_tools.

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

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

The description adds behavioral details beyond annotations: ownership enforcement, soft deactivation rather than deletion, and historical data retention via recent_alerts. This aligns with annotations (destructiveHint=false) and provides transparency about mutation effects.

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

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

The description is three concise sentences with no fluff. The first sentence states the core action, the second adds ownership context, and the third explains the deactivation behavior. 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 one-parameter mutation tool with idempotency hint, the description covers purpose, usage, and behavior. It lacks mention of potential errors or idempotency implications, but overall it is fairly complete given the tool's complexity.

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

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

With 100% schema coverage, the description adds little new information. It notes the ID is returned by subscribe, which the schema already states. No additional semantic guidance is provided.

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

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

The description clearly states the action 'Cancel a subscription by id,' specifies the resource (subscription), and includes ownership scope. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by noting the cancellation behavior and linking to 'recent_alerts'.

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 context: ownership is enforced, so only own subscriptions can be canceled. It does not directly state when not to use or list alternatives, but the condition is clear from the ownership constraint and reference to recent_alerts.

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 (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent with the description. The description adds valuable context by detailing the return values: verdict, extracted structured form, actual value with citation, and percent delta. This fully discloses the tool's behavior beyond annotations.

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

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

The description is a single paragraph but efficiently conveys usage, domain, output, and value proposition. It front-loads the key verb and resource. Slightly more structure (e.g., bullet points for outputs) could improve readability, but it is concise and informative.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete. It explains what types of claims are supported and what the output contains. It could mention error cases or limitations (e.g., unsupported claims return 'unsupported'), but the 'v1 supports' qualifier acknowledges future scope.

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

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

Schema coverage is 100% for the single parameter 'claim'. The description adds significant meaning by providing examples ('Apple's FY2024 revenue was $400 billion') and specifying the domain (company-financial claims). This goes beyond the schema's generic description.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples of use cases and explicitly defines the domain (company-financial claims for public US companies). This distinguishes it from sibling tools like 'get_fact' or 'get_facts', which are more general.

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 whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain limitation (company-financial claims) and mentions that it replaces multiple sequential calls. It does not explicitly state when not to use or list alternatives, but the domain restriction provides clear guidance.

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