hackernews

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

Discloses important traits: free default model, BYO key for Anthropic (cost implication), scoring range (0-100), and return structure (per-model + combined). Annotations confirm non-destructive, idempotent, read-only – no contradictions.

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

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

Single paragraph front-loading the tool's purpose and output, then key parameters and use cases. Efficient with no wasted words, though could be slightly restructured for skimmability.

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

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

Given 4 parameters, rich annotations, and no output schema, the description adequately covers inputs, behavior, output structure (per-model fields + combined view), and typical use cases. Still room to mention pagination or error handling, but sufficient.

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

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

Schema coverage is 100%, but description adds meaning beyond the schema: e.g., 'entity' examples, default model, supported model values, optional context for disambiguation, and that _apiKey is passed through to api.anthropic.com. This aids correct usage.

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 it probes LLMs for entity knowledge and scores visibility (0-100), distinguishing itself from sibling tools like scan_competitor_ai_presence and compare_entities by focusing on per-model visibility scores with combined view.

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 mentions use cases (AI-marketing audits, brand checks, competitive monitoring), default model, and key requirement for Anthropic. Could be improved by contrasting with similar tools, but current guidance is clear and actionable.

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

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

Annotations already convey safety (readOnlyHint, idempotentHint, openWorldHint). The description adds value by noting that it returns structured answers with citation URIs and routes to an extensive tool set. 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?

Front-loaded with the key preference message, followed by concise examples and a clear list of use cases. Every sentence earns its place; no 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 complexity (single required parameter, no output schema), the description fully covers what the tool does, how to invoke it, and what to expect. The examples and guidance are sufficient for correct 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 aliases documented. Description reinforces by showing example questions and clarifying that the parameter accepts natural language. The examples add practical semantic 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 specific verbs ('routes', 'returns') and identifies a clear resource: questions about current/historical data from 3,745 tools across 884 sources. It distinguishes from web search and provides concrete examples, making the purpose unmistakable.

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 'PREFER OVER WEB SEARCH' for specific data types, lists example queries, and implies when not to use it (non-factual questions) by the nature of the tool. This provides clear when-to-use and when-not-to-use guidance.

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

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

Description adds significant behavioral details beyond annotations: refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and success return fields. It explains the extraction process. Annotations already declare readOnly, idempotent, non-destructive; description reinforces and expands 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 moderately concise (6 sentences) and front-loaded with the core purpose. Every sentence adds value, though it could be slightly shorter without loss. Still well-structured for an agent.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return values, refusal reasons, and behavioral constraints. It provides enough context for an agent to decide when to use and what to expect.

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

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

Schema coverage is 100%, with descriptions for all parameters. The description does not add new parameter semantics beyond the schema (e.g., 'Your question in natural language' is already in the schema). Baseline 3 is appropriate because schema already carries the load.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads. It specifies the verb ('extracts the answer using ONLY what the tool result contains') and the resource (multiple tools across sources). It differentiates from the sibling 'ask_pipeworx' by noting the extra LLM call and the grounded behavior.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with example domains (financial verdicts, legal claims, etc.). Also advises preferring 'ask_pipeworx for casual lookups', giving clear 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?

Description extensively details behavior beyond annotations: classification, fan-out logic, response shapes, resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits, wide-spread handling, and cancellation rule parsing. Annotations (readOnlyHint, idempotentHint) are consistent.

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

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

While verbose, the description is well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver, parent event, news, safety, cancellation). Front-loaded purpose and usage. Minor redundancy (e.g., repeated 'low_confidence_match' explanation) could be trimmed.

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

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

For a complex tool with 3 params and no output schema, the description covers nearly every aspect: input types, behavior variations, response structures, edge cases (closed markets, low confidence, wide spreads), and resolution risks. No gaps identified.

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

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

All three parameters (market, depth, include_raw) are described in schema with 100% coverage. Description adds significant context: market accepts slug/URL/question text, depth defaults to thorough, include_raw defaults false with rationale. Examples further clarify usage.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', specifying verb (research), resource (Polymarket bet), and mechanism (Pipeworx data). The detailed examples and classifiers distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicit usage hints are given: 'Use for "should I bet on X"...' and extensive fan-out examples illustrate contexts. However, no explicit when-not-to-use or direct alternative tool names are provided, though sibling tool list implies 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?

The description adds substantial behavioral context beyond annotations, explaining data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations.

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

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

The description is well-structured with front-loaded examples and actionable guidance. It is slightly lengthy (5 sentences) but each sentence adds value. No fluff present.

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

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

The description covers purpose, usage, data sources, return format, and efficiency gains. It lacks explicit mention of error handling or limitations, but overall provides sufficient context for an agent to decide 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?

With 100% schema coverage, the description enriches parameter understanding by explaining that 'values' are tickers/CIKs for companies and drug names for drugs, and clarifies the min/max items range with examples. It adds context not present in 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 performs side-by-side comparison of 2-5 companies or drugs using specific data sources (SEC EDGAR for companies, FAERS/FDA for drugs). It distinguishes itself from sibling tools like entity_profile by explicitly noting it replaces sequential single-entity lookups.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. It does not explicitly list alternative tools for single entity queries, but the context of multi-entity comparison is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds beyond this: account requirement, depth tier restriction ('thorough' requires paid plan), expected duration, and behavior like extracting gaps[] for unanswered facets. 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 informative but slightly verbose. It covers all key aspects in a structured manner, front-loading the core function. Each sentence adds value, though some details could be condensed. Overall well-organized.

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

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

Despite no output schema, the description thoroughly explains the return value: 'structured findings packet' with evidence, confidence, source, fetched_at, citation, and gaps. It also covers prerequisites (account), time expectation, and depth levels. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds context like 'quick=3, standard=5, thorough=8' which is also in the schema's enum descriptions. It reinforces the purpose but doesn't add significant new meaning beyond the schema.

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

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

The description clearly states it performs 'grounded multi-source research in ONE call', decomposing questions and routing to tools. It distinguishes from sibling tools like ask_pipeworx, specifying it's for broad or multi-part questions. The verb 'research' and resource 'multi-source' are specific.

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

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

Explicit usage guidance: 'Use for broad or multi-part questions' with examples, and 'use ask_pipeworx for single lookups'. It also mentions requirements (Pipeworx account, paid plan for thorough depth) and expected time (15-60s).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds operational details: returns top-N most relevant tools with names, descriptions, full input schemas with curated examples, and each result is ready to call directly. This adds value beyond annotations, but annotation coverage was already high.

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

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

The description is concise with two paragraphs. The first sentence states the purpose, followed by examples and return format. It is front-loaded with the most important information and every sentence adds value.

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

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

Given no output schema, the description explains return structure (names, descriptions, schemas, ready to call). It covers input parameter semantics and usage guidance. Could mention edge cases like empty results, but overall complete for a discovery 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 all parameters described. The description adds meaning by explaining that the query parameter accepts natural language and lists aliases (task, q, search, description). It also tells that results include curated examples and are ready to call, adding context beyond the schema.

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

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

The description clearly states the verb 'Find' and the resource 'tools' by describing data or task. It lists many data categories and explicitly distinguishes from sibling tools by saying 'Call this FIRST when you have many tools available and want to see the option 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 explicit when-to-use guidance: 'when you need to browse, search, look up, or discover what tools exist for:' and 'Call this FIRST when you have many tools available'. It implies not to use when you already know the tool, but could be more explicit about 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?

The description complements annotations (readOnlyHint, idempotentHint) by detailing how it fans out across multiple sources and returns specific fields. It also discloses the USPTO patents API soft-fail until May 2025, adding behavioral context beyond what annotations provide. No contradiction.

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

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

The description is a single paragraph but front-loaded with concrete example queries. Every sentence adds value: listing data sources, outputs, and limitations. It is concise and well-structured given the tool's complexity.

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

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

Despite no output schema, the description comprehensively explains return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes soft-fail for USPTO. This provides sufficient context for an agent to understand what the tool returns.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond schema descriptions: it specifies that only 'company' type is supported, value must be ticker or zero-padded CIK, and names not supported (with fallback to resolve_entity). This aids correct parameter usage.

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 a US public company, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs. It distinguishes from siblings like compare_entities and resolve_entity by offering a holistic view in one call.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity first if only a name is available. This provides clear guidance on when to use the tool and when not to.

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 destructiveHint=true and idempotentHint=true. The description adds no further behavioral context beyond confirming deletion. No contradiction, but little additional value 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?

Extremely concise, two sentences that are front-loaded with the essential action. Every word earns its place, no fluff.

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

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

For a tool with one required parameter, no output schema, and rich annotations providing safety and idempotency info, the description provides sufficient context including usage guidelines and sibling references.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The tool description does not add extra meaning about key format, uniqueness, or constraints 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 action: 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), and distinguishes from siblings 'remember' and 'recall' by explicitly pairing with them.

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

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

Provides explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions alternatives by pairing with 'remember' and 'recall'.

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 details the process (fetches page, extracts title/description/key links, emits standard format) and output format, adding behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). No contradiction with annotations.

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

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

The description is very concise with two main sentences and a bullet list of use cases. It front-loads the primary purpose and is structured logically, with 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?

Despite no output schema, the description clearly states the output is a single text blob in standard llms.txt markdown format. Annotations cover safety and idempotency, and parameters are fully documented. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents the two parameters. The description does not add new information beyond what is in the schema; it only repeats that output is a text blob. 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 that the tool generates a production-ready llms.txt file for any URL, specifying the input (URL) and output (markdown format). It distinguishes the tool's specific function from sibling tools, many of which are research or alert-based.

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

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

The description lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitors. While it provides good context for when to use, it does not explicitly compare to sibling tools like ai_visibility_check or scan_competitor_ai_presence to aid in 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?

Beyond annotations (readOnlyHint, idempotentHint), description adds specific return fields (text, score, author, timestamp, child replies), informing agent of output structure. No contradictions with annotations.

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

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

Single sentence efficiently conveys purpose, example, and return fields. No redundancy; all information earn its place.

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

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

Given simple tool (1 param, output schema exists), description adequately explains what it does and what it returns. No gaps for agent to select and invoke correctly.

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

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

Schema covers 100% with description 'numeric Hacker News item ID'. Description adds concrete example ('42153809') and clarifies that it fetches stories or comments, reinforcing usage context.

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 'Fetch a Hacker News story or comment by ID', specifying verb (fetch) and resource (HN story/comment). Clear distinction from sibling tools like search_hn (search) and get_top_stories (list).

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?

Implies usage when a specific ID is known, but lacks explicit guidance on when not to use or alternatives. Context is clear but no exclusions or direct sibling differentiations.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds context by listing the specific return fields, providing additional transparency 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, concise sentence that front-loads the action and lists return fields. Every part contributes useful 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?

Given the tool's simplicity (one optional parameter, output schema exists), the description provides adequate context. It could mention limitations like no historical data, but overall it is sufficient for an AI agent to use correctly.

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

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

The schema coverage is 100% with the 'count' parameter described. The description does not add further meaning beyond what the schema provides, so baseline score of 3 applies.

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

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

The description clearly states it retrieves current top-ranked Hacker News stories and specifies the return fields (titles, URLs, scores, etc.), distinguishing it from sibling tools like search_hn or get_item.

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 does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions. The usage is implied by the name and context but lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about default behavior (active subscriptions) and return fields, but does not provide significant additional behavioral insight beyond what annotations convey.

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

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

Description is two sentences: the first clearly states purpose and output fields, the second provides usage guidance. No filler, front-loaded, 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 list tool with one parameter and no output schema, the description covers purpose, return fields, and usage context. It does not mention pagination or limits, but these are not critical for this 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 description coverage is 100% for the single optional parameter 'include_inactive'. The description does not add new meaning beyond the schema; it rephrases the default behavior but adds no extra semantics.

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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools subscribe and unsubscribe by focusing on viewing instead of modifying.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Implicitly contrasts with subscribe and unsubscribe siblings, but does not name them directly.

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 are neutral (readOnlyHint=false etc.) and the description does not contradict them. It discloses additional behavioral traits: rate-limited to 5 per identifier per day, does not count against tool-call quota, and that feedback is reviewed daily and influences roadmap. This goes beyond what annotations provide.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then covers usage, constraints, and preparation tips. Every sentence provides necessary information without redundancy or fluff.

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

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

Given the tool's complexity (multiple feedback types, optional context object, rate limits), the description covers all essential aspects. It explains when to use each type, what information to include, and system constraints. Without an output schema, the description sufficiently informs about the tool's behavior and outcome.

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

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

Schema coverage is 100%, so the description adds moderate value. It reinforces the enum meanings and provides guidance on how to structure the message (be specific, mention tool/error). While some info is duplicated from schema, the usage advice adds semantic context for the agent.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses a specific verb ('Tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools which focus on queries and research rather than feedback submission.

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

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

The description explicitly states when to use the tool: for bugs, missing features/data gaps, or praise. It also tells the agent what not to do ('don't paste the end-user's prompt') and provides context on each feedback type. Rate limits and quota impact are mentioned, giving clear guidance on usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds specifics: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and output format (pack, tool, count). 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 brief yet comprehensive, using bullet points for use cases and concise sentences. Every sentence adds value without redundancy.

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

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

Given the simple schema (1 param, no output schema), the description fully explains return values and caching behavior. No gaps remain for an AI agent to misunderstand the tool's capabilities.

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 description for 'window' parameter. The main description mentions the window options but does not add significant new meaning beyond what the schema already provides. Baseline 3 is appropriate, with +1 for the concise context added.

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 what the tool does: returns trending tools, packs, and call volume based on other AI agents' calls. It distinguishes from siblings like discover_tools by focusing on real-time trends rather than static listings.

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

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

Three explicit use cases are given (discovering hot data sources, confirming canonical tool, aligning use case). While alternatives are not mentioned, the context is clear enough for an AI agent to decide when to use this tool.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: error on missing args, response structure (opportunities[], partition_check), fill check with realizable_edge_pp, semantic anchor, partition filter. 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?

Description is dense and informative, but somewhat verbose (15 sentences). It is well-structured front-loading the requirement, but could be more concise. Every sentence adds value, but some details could be streamlined.

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 (two modes, multiple checks, no output schema), the description is remarkably complete. It explains the algorithm, fill check, semantic anchor, partition filter, and response fields. No important aspect seems missing.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond schema: provides examples of slugs and seed questions, explains what the tool does with them (walks markets, checks monotonicity). Even though baseline is 3, the additional context earns a 4.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two modes (event and topic) and distinguishes from sibling tools like polymarket_fill_risk. The verb 'Find' plus resource 'arbitrage opportunities' is specific and actionable.

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 requires one of 'event' or 'topic' and states 'call with no args fails.' Provides recommendations: 'event (recommended for a specific market)' and explains when to use each mode. Also references sibling tool polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds rich context: caching behavior, model family details, edge calculation with slippage, and diagnostic fields. No contradiction.

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

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

The description is long but well-organized into sections (model families, output fields, knobs, diagnostics). Front-loaded with purpose. Could be slightly more concise but every sentence adds value.

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

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

Given 9 parameters with no output schema, the description fully covers output structure (by_segment, diagnostics) and behavior. It explains caching, edge calculation, and filtering logic, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema—e.g., explains slippage rationale, why min_kelly doesn't filter partitions, and how min_partition_leg_kelly applies. All parameters have enhanced descriptions.

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

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

The description uses specific verbs ('Scan', 'return') and clearly states it identifies opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edges from multiple model families.

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 the tool is for 'what should I bet on today' and provides clear filtering knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly contrast with the sibling polymarket_arbitrage or specify when to use one over the other.

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

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

The description adds substantial behavioral context beyond annotations: it explains the data source (daily snapshots), response structure (tracked, expired, snapshot_dates), decay computation on absolute value, and limits. Annotations already indicate safe read operations, and the description complements them without contradiction.

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

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

The description is relatively long but well-structured, starting with a core question and then explaining response fields and limits. Every sentence adds value, though it 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?

Given the tool's complexity (time-series, decay metrics, expired opportunities) and no output schema, the description is very thorough. It explains all response fields and covers limits and interpretation, making it complete for an agent.

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

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

Schema coverage is 100% with both parameters described. The description adds minor context like defaults and clamps but does not significantly enhance meaning beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about edge freshness and differentiates from sibling polymarket_edges by focusing on time-series and decay.

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 uses a quoted question to indicate when to use the tool and contrasts fresh vs old edges. It also mentions limits like 60-day TTL and daily closes instead of intraday. However, it does not explicitly state when not to use it or name 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?

The description discloses behavioral traits beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains that the tool walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and details outputs for both modes. It also warns about the dominant loss mode in arb-bot P&L. No contradiction with annotations.

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

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

The description is lengthy but well-structured, with clear sections for each mode and usage guidance. It is front-loaded with the core purpose and uses capitalization for emphasis (REQUIRES, SINGLE-MARKET, BASKET). However, it could be slightly more concise without losing essential detail; the parenthetical explanations and long lists of outputs are necessary but add verbosity.

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

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

The description is comprehensive given the absence of an output schema. It explains all outputs for both modes, input parameters with defaults and constraints, and the rationale behind using the tool. It also covers edge cases like partial fills and directional risk, leaving no major gaps in understanding for a properly equipped AI 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?

Despite 100% schema description coverage, the description adds significant meaning beyond the schema. It explains the different interpretations of size_usd in single-market vs basket mode, the default auto logic for side in basket mode, and clamping ranges. It also contextualizes each parameter within the tool's overall operation, enhancing usability 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 the tool's function as a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket). It lists specific outputs and explicitly relates to sibling tools like polymarket_arbitrage and polymarket_edges, making its purpose unambiguous.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why it's needed (theoretical overround on thin books is not capturable, partial basket fills convert an arb into an unhedged directional position), providing clear context for decision-making.

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 read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context: explains compatibility_warning conditions, temporal_alignment field, skipped_cross_type/subtype counters, and when spreads are meaningless. 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 each sentence serves a purpose. It is front-loaded with the core function and modes. Could be slightly more structured (e.g., bullet points for modes), but the information density is high without redundancy.

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

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

Given no output schema, the description thoroughly explains return fields (top_spreads_pp, compatibility_warning, temporal_alignment, counters) and edge cases (non-equivalent bet shapes, temporal gaps). It covers all necessary aspects for an agent to correctly interpret results.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by listing the exact topic shortcuts, explaining override behavior, and providing example values. This reinforces but does not significantly expand on the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit pairing) and differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly explains when to use (cross-venue spread comparison), how to use (topic or explicit parameters), and when not to rely on results (compatibility_warning for non-equivalent bet shapes or temporal misalignment). It also warns that most pre-mapped topics are not tradeable.

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 scoping details (anonymous IP, BYO key hash, account ID) and pairs with related tools, enhancing transparency beyond annotations.

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

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

Three sentences front-loaded with the primary action. Every sentence serves a purpose: core function, usage hint, and tool relationships. No wasted words.

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

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

For a simple read-only tool with one parameter, the description covers the operation, scoping, and sibling tools. Lacks output format details but is sufficient for agent decision-making.

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

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

Schema coverage is 100%, and the description adds the key insight that omitting the key lists all saved keys, which is not inferred from 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 retrieves a value saved via 'remember' or lists all keys when no argument is given, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Provides explicit context for use: 'look up context the agent stored earlier... without re-deriving it from scratch.' Does not enumerate when not to use, but the pairing with remember/forget gives clear guidance.

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

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

Disclosure consistent with read-only, idempotent annotations. Adds specifics: returned fields, mark_read flag behavior, and that polling is acceptable.

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 no wasted words. Front-loaded with main purpose, then filters, then mark_read, then polling note. 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?

No output schema, but description explains return values (source, citation_uri, raw payload). Covers all parameters, behavior, and even alternative access method. 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%, yet description adds significant behavioral context beyond schema, e.g., mark_read causes newer-only results on subsequent calls, and output format details.

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

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

Clearly states it pulls fired events from subscription feed, listing returned fields (source, citation_uri, raw payload). Distinct purpose from sibling tools like list_subscriptions.

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

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

Provides explicit usage tips: filtering by type/since, setting mark_read, and notes polling is fine. Mentions alternative endpoint for scripts/dashboards, but does not exhaustively contrast with all 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, etc.), the description details multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail), parallel execution, parameter formats (ISO date vs relative shorthand), and return structure (changes grouped by source + citation URIs). No contradictions with annotations.

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

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

The description is concise yet thorough, front-loaded with purpose and examples. Every sentence adds unique value—fallback behavior, parameter formats, return format, and sibling differentiation—without redundancy.

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

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

Given the complexity (3 params, no output schema, multi-source with fallbacks), the description covers all essential aspects: purpose, parameters, behavior, return structure, and when to use an alternative. No gaps remain.

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

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

Although schema coverage is 100% (baseline 3), the description adds practical guidance: recommended 'since' values ('30d', '1m'), supported identifiers (ticker vs CIK), and the current limitation of 'type' to 'company'. This enriches the parameter documentation.

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

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

The description opens with example queries ('What's new with X', 'latest on Y') and clearly defines the tool as a change feed for a company in a time window. It explicitly contrasts with sibling entity_profile for static data, making the purpose unmistakable.

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 directs agents to use entity_profile instead when a static profile is needed, providing a clear when-not-to-use. It also gives examples of natural language queries that trigger this tool, making usage intuitive.

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 context beyond annotations: memory persistence (24 hours for anonymous, persistent for authenticated), scoping by identifier. No contradiction with annotations (idempotentHint=true is consistent with storing without side 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?

Three sentences, no redundancy, front-loaded with purpose. 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?

No output schema, but the description states what happens (stores data). Might benefit from mentioning return value, but for a memory tool it's adequate.

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

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

Both parameters are described with examples and purpose. Schema already provides descriptions (100% coverage), but the description adds contextual value like 'findings, addresses, preferences' for value.

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

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

The description explicitly states the tool's purpose: 'Save data the agent will need to reuse later.' It identifies the action (save), resource (data as key-value pairs), and distinguishes it from sibling tools like recall and forget.

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

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

Clear guidance on when to use: 'Use when you discover something worth carrying forward.' Alternatives are named: 'Pair with recall to retrieve later, forget to delete.' Also specifies session persistence details.

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

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

Annotations declare readOnlyHint, idempotentHint, etc. Description adds that it cascades through several endpoints and returns specific citation URIs. No contradictions.

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

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

Well-structured with examples first, then usage instruction, then type details. Slightly verbose but 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?

No output schema, but description explains return values thoroughly (ticker, CIK, RxCUI, citation URIs). Covers both entity types comprehensively for a lookup tool.

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

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

Schema coverage is 100%. Description adds meaning: for company, input can be ticker, CIK, or name; for drug, brand or generic. Also explains output details per type.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with specific examples like 'ticker for...' and 'CIK for...'. It distinguishes from siblings by being the primary resolver for identifiers.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides context that it replaces multiple lookups. No explicit when-not-to-use, but guidance is strong.

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

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

Adds meaningful context beyond annotations: explains it probes each entity, ranks results, and surfaces scores. Annotations already cover readOnly, openWorld, and idempotent nature, so description complements 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?

Three sentences front-load purpose and method, include concrete example. No redundant information; 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, parameters, and output structure (ranked list with fields). No output schema, but description adequately describes return values. Could explicitly mention JSON format, but not critical.

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?

All 4 parameters have schema descriptions (100% coverage). Description adds context: 'entities' limited to 2-8 and first treated as subject, 'context' disambiguates names. Enhances understanding 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?

Clear verb 'Compare' with specific resource 'AI visibility across multiple entities'. Distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic) by naming the method and use case.

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

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

Description specifies usage for competitive AI-marketing audits with an example. Implicitly distinguishes from single-entity and general comparison tools, but lacks explicit when-not-to-use or 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 declare readOnlyHint, idempotentHint, and openWorldHint. Beyond that, the description adds valuable behavioral context: it fans out across two sources, explains partial failure graceful degradation, and warns that bundlephobia's first measurement can take 5-30s. 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 single dense paragraph that efficiently conveys purpose, usage, return fields, limitations, and edge cases. It could be improved with bullet points for readability, but it is not verbose and is front-loaded with the core function.

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 having no output schema, the description lists the return fields (summary block, advisories, links, alternatives) and covers error handling. It could be more explicit about the return structure, but the detail provided is sufficient for a tool with only two 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?

The input schema covers 100% of parameters with descriptions. The description restates the defaults and adds context about npm ecosystem, but does not provide substantial new 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 it is a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the exact use case: when an agent asks about safety, popularity, size, or cost of adding a package. No sibling tool does this, so it effectively distinguishes itself.

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 when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM ecosystem limitation and directs other ecosystems to deps.dev:version directly, providing clear alternatives 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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing a safe read operation. The description adds value by specifying the returned fields (titles, URLs, scores, author names, timestamps). However, it does not disclose behavior such as sorting order, maximum results beyond the per_page parameter, or rate limits. This is adequate but not exhaustive.

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

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

The description is two sentences long, with no unnecessary words. It front-loads the purpose and follows with return information. Every sentence adds value, and the structure is efficient.

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

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

Given the presence of an output schema and comprehensive annotations, the description is fairly complete. It mentions return fields, which is useful. However, it lacks guidance on usage context compared to sibling tools and does not mention sorting or result limits beyond the per_page parameter. It covers most necessary aspects for a simple search tool.

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

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

Schema description coverage is 100%, with each parameter already described in the schema. The tool description does not add additional meaning or context beyond what the schema provides. Baseline score of 3 is appropriate as the description meets the minimum standard without enhancing parameter understanding.

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

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

The description clearly states the verb 'search' and the resource 'Hacker News', specifying that it searches for stories, comments, and users by keyword. It also lists the returned fields (titles, URLs, scores, author names, timestamps). This distinguishes it from sibling tools like 'get_item' and 'get_top_stories', which serve different purposes.

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 implies that the tool is for keyword-based searches on Hacker News, but it does not explicitly state when to use it over alternatives like 'get_item' or 'get_top_stories'. No when-not-to-use or alternative recommendations are provided, leaving the agent to infer the appropriate context.

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

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

Annotations already indicate safe read operation (readOnlyHint, idempotentHint). Description adds details beyond annotations: embedding model (BGE-base-en), window size (500-char), similarity function (cosine), character limit (200K) and truncation behavior. 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?

Single paragraph, front-loaded with core action. Every sentence adds information. Could be slightly more structured (e.g., bullet points for constraints), but efficient for length.

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

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

Despite no output schema, description explains return values (passages with offsets and scores). Covers constraints (max chars, truncation flag). Provides enough context for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining 'text' as document text, 'query' with examples, and 'limit' as max passages. Also hints at return format (offsets and scores) despite no output schema.

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

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

Clearly states it performs semantic search inside a fetched record, with examples like 'SEC 10-K body' and 'article'. Distinguishes from siblings 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: when record is too large for prompt. Mentions alternative workflow with ask_pipeworx_grounded. Does not explicitly state 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 indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. Description adds important behavioral details: OAuth requirement, phone verification cap of 10/day, webhook HMAC signing, auto-disable after 10 failures. Exceeds annotation coverage.

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 for types, delivery channels, and examples. Packed with information but not overly verbose; every sentence adds value. Slightly long but justified by complexity.

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

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

Given 3 parameters with nested objects and no output schema, the description covers return value (new subscription id), auth requirements, delivery constraints, and per-type parameter details. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds significant meaning beyond schema: explains each subscription type with examples, per-type parameter structures, and detailed delivery channel options including validation constraints. Greatly aids parameter usage.

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, with specific verb 'create' and resource 'subscription'. It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by detailing subscription types and delivery options.

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 context: requires Pipeworx OAuth account, cannot be used with anonymous or BYO users. Lists supported types and delivery channels. Does not explicitly say when not to use or contrast with alternatives, but context is sufficient.

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

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

Description aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) and adds detail: returns non-destructive, read-only category-bucketed example questions with exact tool+argument shapes. 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 front-loaded with common queries but is somewhat lengthy. Every sentence adds value, but minor trimming could improve conciseness while preserving clarity.

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

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

Given no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes) and covers purpose, parameters, and usage context. Complete for an onboarding 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%. Description adds meaning by explaining the 'topic' parameter with example values and behavior (omit for full spread vs. specify for focus), surpassing the schema's terse 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?

Description clearly specifies the tool's purpose: onboarding entry point for generating example questions about Pipeworx capabilities. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on idea generation and learning meta-tool usage.

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

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

Explicitly states when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and provides guidance on optional topic parameter usage for focused vs. broad queries.

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

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

The description adds beyond annotations by specifying that the row is deactivated (not deleted) and that historical events remain available via 'recent_alerts'. This explains the non-destructive nature and side 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: main action, ownership constraint, and deactivation behavior. No fluff, front-loaded with purpose.

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

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

Given the simple tool (one parameter, no output schema, good annotations), the description covers purpose, ownership, and side effects completely. No missing information.

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

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

While the schema describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe', the description adds that ownership is enforced, implying the id must belong to the current user. This adds meaningful context.

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') and the resource ('by id'), and the title 'Unsubscribe from Alerts' aligns. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description provides context on ownership enforcement ('you can only cancel your own subscriptions'), giving a clear usage guideline. It does not explicitly contrast with sibling tools but implies the correct context.

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

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

The description adds significant behavioral context beyond annotations: it reveals the data source (SEC EDGAR + XBRL), the output format (verdict with structured form, actual value, citation, percent delta), and the efficiency improvement (replaces 4-6 calls). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint, and the description does not contradict these.

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

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

The description is front-loaded with trigger phrases and provides all necessary information in a dense paragraph. It could be slightly more concise, but the content is well-organized and every sentence serves a purpose.

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

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

Despite the complexity of the tool (natural-language claim verification), the description covers all essential aspects: supported domain, data source, return values, and efficiency. Since there is no output schema, the description adequately explains the output format. The tool's limitations are also acknowledged, making it complete for its purpose.

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 single parameter 'claim' already has a detailed description in the input schema. The tool description enhances this by providing concrete examples and clarifying the supported claim type (company-financial). Since schema coverage is 100%, the description adds extra value but does not compensate for missing schema details.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources, specifically company-financial claims for US public companies. It uses specific action verbs like 'verify', 'confirm or refute', and explicitly distinguishes itself from potential sibling tools by noting it replaces multiple sequential calls.

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

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

The description provides explicit guidance on when to use the tool: 'whenever the agent needs to check whether something a user said is factually correct'. It also hints at limitations (v1 supports only company-financial claims), but does not explicitly state when not to use or list alternative tools for other claim types. However, this is adequate for most scenarios.

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