spacenews

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

Discloses probing multiple models, default model, need for separate Anthropic API key, cost implications, and return format, adding value beyond annotations indicating read-only and idempotent behavior.

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

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

Two well-structured sentences delivering core info, return format, and use cases 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?

Covers main functionality, return structure, and key context (API key needed for Anthropic) but lacks error handling details; adequate given tool simplicity.

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

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

Schema coverage is 100% with good descriptions; description adds examples and clarifies default behavior, 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?

Clearly states the tool probes LLMs for brand visibility, scores per model (0-100), and distinguishes from siblings like ask_pipeworx or search_articles by focusing on AI awareness scoring.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch checks, competitive monitoring) but does not mention when not to use or alternative sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it routes to a large pool of tools, fills arguments, and returns structured answers with stable citation URIs. No contradictions. Minor lack of details on failure modes or rate limits is acceptable given annotations.

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

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

Description is efficiently front-loaded with a strong directive and list of domains. It uses bullet-like style without formatting, and each sentence contributes information. Slightly longer than necessary but well-organized; could be trimmed without losing 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 should explain the return format more thoroughly. It mentions 'structured answer with stable pipeworx:// citation URIs' but lacks details on error handling, pagination, or structure when query fails. Input side is well-covered, but output completeness is lacking.

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

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

Schema has 6 parameters all as aliases for 'question', with 100% coverage. Description enhances this by explaining the kind of input expected (natural language factual queries) and providing examples, which adds meaning beyond the schema's simple type and description.

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

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

The description clearly states the tool routes factual questions to 3,745 tools across 884 sources, distinguishing it from web search by emphasizing authoritative structured data with citations. It lists specific domains and provides examples, making the purpose highly 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 advises 'PREFER OVER WEB SEARCH' and provides a list of trigger phrases ('what is', 'look up', etc.) and examples. However, it does not explicitly contrast with sibling tools like deep_research or entity_profile, leaving some ambiguity about when to choose ask_pipeworx over them.

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. The description adds value by detailing the extra LLM call cost, return format with fields like evidence and refusal_reason, and the explicit refusal mechanism. No contradiction with annotations.

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

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

The description is well-structured with a clear purpose first, followed by details on cost, return format, and refusal reasons. While slightly lengthy, every sentence adds value and is efficiently organized.

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

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

Given the tool's complexity (routing across 3,745 tools), the description covers the mechanism, return format, refusal reasons, and appropriate use cases. No output schema exists, but the description thoroughly explains the response.

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

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

Schema coverage is 100%, with all parameters described as aliases for 'question'. The description does not add additional semantics beyond what the schema already provides, so baseline 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 is a 'Hallucination-resistant answer mode for high-stakes reads,' specifies the routing and extraction process, and distinguishes it from the sibling tool 'ask_pipeworx' for casual 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?

It explicitly states when to use (for quoted/cited/acted-on answers) and when to prefer the alternative casual sibling, providing clear context and exclusion criteria.

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral detail: how market resolution works (resolver contract, match confidence), fan-out logic, handling of closed/dead markets, spread warnings, cancellation rules, and suppression of analysis on low-confidence matches. 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 very long (multiple paragraphs) with extensive detail. While packed with useful information, it lacks conciseness. The initial sentence is good, but the length may overwhelm 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?

Despite no output schema, the description fully explains the return structure (result.market, result.analysis, result.evidence, etc.) and all edge cases (low confidence, closed markets, wide spreads, cancellation rules). It covers safety checks and user guidance thoroughly.

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

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

Schema coverage is 100% with parameter descriptions. The description adds clarity: market parameter specifies acceptable inputs (slug, URL, question text), depth explains quick vs thorough, include_raw explains default behavior and when to use true. Adds value beyond schema.

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

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

The description starts with a clear verb 'Research' and resource 'Polymarket bet', and explains it pulls 'Pipeworx data'. It distinguishes itself from siblings like `polymarket_arbitrage` and `polymarket_edges` by focusing on a single bet's data aggregation.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides detailed fan-out examples and warning about result checking. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already indicate safe read-only behavior. The description adds critical behavioral details: parallel execution, handling of off-calendar fiscal years, sorted results by primary metric, and return of citation URIs. No contradictions.

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

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

The description is somewhat lengthy due to examples and data details, but the core purpose is front-loaded and each sentence adds value. It could be shorter without losing clarity.

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

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

Given no output schema, the description adequately explains the return format (paired data with citation URIs). It covers expected behavior for both entity types and addresses edge cases (off-calendar fiscal years). Sufficiently complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the data source and behavior based on the 'type' enum and giving examples for 'values' array items. This goes 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 performs side-by-side comparison of 2–5 companies or drugs, listing specific data pulled (SEC filings, FAERS counts) and resources (SEC EDGAR/XBRL). It distinguishes from sequential lookups by explicitly preferring this tool.

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

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

The description tells when to use the tool ('compare X and Y', 'which is bigger') and explicitly states to prefer it over sequential lookups. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Beyond annotations (readOnlyHint, destructiveness), description adds behavioral traits: decomposition, parallel routing, evidence extraction with citations, gap identification, and expected response time (15-60s). 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 well-structured and front-loaded with core purpose. Each sentence adds value, but length could be slightly trimmed without losing information. Overall efficient.

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

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

Despite no output schema, description thoroughly explains return format (structured findings with evidence, gaps) and covers all necessary aspects for a complex orchestration tool. Completely sufficient for agent understanding.

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

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

Schema covers both parameters (100% coverage). Description adds practical context by explaining enum values (quick=3, standard=5, thorough=8) and noting that question can be broad/multi-part. Exceeds baseline 3 by providing usage nuance.

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 into sub-questions. It distinguishes itself from sibling tool ask_pipeworx by contrasting multi-part vs single lookups.

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

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

Explicitly describes when to use: broad or multi-part questions. Provides alternatives (ask_pipeworx for single lookups) and requirements (Pipeworx account, paid plan for thorough depth).

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds details beyond annotations: 'returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clearly explains the output behavior and reusability. 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, well-structured paragraph that front-loads the purpose. Every sentence is informative, with concrete examples and clear action statements. No unnecessary words.

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

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

Given the tool is a discovery tool with 6 parameters (mostly aliases) and no output schema, the description is sufficiently complete. It explains what the output contains, how to use it, and provides examples. The agent has all needed information to 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 coverage is 100% with all parameters described. The description adds value by noting multiple aliases for the query parameter (task, q, description, search) and providing two concrete examples. This consolidates and enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It is specific about the use case (browsing, searching, discovering) and lists many example domains. The tool is distinguished from siblings by being a meta-tool for discovery, not direct data retrieval.

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

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

The description provides explicit when-to-use guidance: 'Call this FIRST when you have many tools available and want to see the option set.' It also gives example queries. However, it does not explicitly state when not to use or compare directly with sibling tools, but the 'first' directive implies prioritization.

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 readOnly, idempotent, and non-destructive hints. The description adds behavioral details beyond annotations: it fans out across multiple APIs, handles USPTO soft-fail, GDELT→GNews fallback, and specifies accepted input formats (ticker or CIK, not names). 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 dense but well-organized: starts with user intents, explains tool preference, then lists outputs and behavior. It could be slightly trimmed (e.g., the list of returned items is long), but every sentence adds value. Good front-loading.

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 complexity (multiple sources, fallbacks, soft-fails), the description covers the main behaviors and outputs. It does not describe output format or pagination, but the list of returned fields is detailed. Without an output schema, it provides sufficient context for an agent to understand 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%, baseline 3. The description adds meaning beyond schema: explains that type is only 'company' for now, value must be ticker or zero-padded CIK, and clarifies that names are not supported—directing to resolve_entity. This enriches the schema 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 it provides a full cross-source profile of a US public company in one parallel call. It lists specific data sources and outputs, and distinguishes itself from sibling tools like resolve_entity (which handles name resolution) and other tools that do single-source 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 recommends preferring this tool over chaining single-pack lookups for holistic views. It provides example user intents and notes that names are not supported, directing users to resolve_entity first. It does not explicitly list when not to use it, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description aligns with these (delete operation) but adds no extra behavioral context 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?

Three sentences, front-loaded with action, no wasted words. Efficient and clear.

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

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

Simple tool with one parameter, no output schema, and good annotations. Description covers purpose and usage adequately, plus pairing advice. No gaps.

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

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

Schema coverage is 100% with clear parameter description. Description adds no new meaning beyond 'by key', so baseline score of 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly describes when to use: 'context is stale, task done, or clear sensitive data'. Provides context with sibling pairing, but lacks explicit 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral details: it fetches the page, extracts specific elements (title, description, key links), and outputs a single text blob in standard format. No contradictions.

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

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

The description is front-loaded with the main purpose and structured with a clear list of use cases. Every sentence is informative and necessary, with no wasted words.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers the what, how, and output format adequately. It explains the return value as a single text blob, which compensates for the lack of output schema. Minor gap: no mention of error handling or required permissions, but context signals show low complexity.

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

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

Schema coverage is 100% with both parameters well-described. The description does not add significant new semantics beyond what the schema already provides (e.g., 'url' and 'max_links' are already explained). Baseline is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the actions: fetches the page, extracts title/description/key links, and emits standard markdown. It distinguishes itself from siblings which are about other content types (e.g., articles, blogs) or different operations.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting an llms.txt for one's own project, or auditing a competitor's AI visibility. While it doesn't mention when not to use or alternatives, the context is clear and helpful for an agent.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it returns specific fields and is sorted, but no additional behavioral context beyond annotations.

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

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

Two sentences, front-loaded with verb+resource, then return fields. No wasted words.

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

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

Given the low complexity (one optional parameter, output schema exists), the description fully covers purpose, output, and ordering without missing essential details.

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

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

Schema covers the 'limit' parameter 100%, so description adds no extra meaning for the parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool fetches latest spaceflight news articles sorted by publication date, distinguishing it from siblings like 'search_articles' (likely searches) and 'get_blogs' (different content).

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

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

Implied usage for fetching recent articles, but no explicit when-to-use or when-not-to-use compared to alternatives like 'search_articles'. No exclusions mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that results are sorted by publication date and returns specific fields, providing useful behavioral context beyond annotations.

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

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

A single, front-loaded sentence that efficiently conveys the action, resource, and output. No wasted words.

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

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

Given output schema exists, the description need not detail return values but still mentions them. The tool is simple with one optional parameter, so the description is sufficiently complete.

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

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

Input schema coverage is 100%, so the schema already documents the 'limit' parameter. The description adds no additional parameter meaning beyond what the schema provides.

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

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

The description clearly states the verb 'fetch' and the resource 'latest spaceflight blog posts', and lists the returned fields. This distinguishes it from sibling tools like get_articles which likely cover broader topics.

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 usage for fetching spaceflight blog posts but does not explicitly state when not to use it or provide alternatives. The context is clear, but exclusions are missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful details about returned fields and optional parameter, but doesn't contradict annotations.

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

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

Two sentences, no redundancy, front-loads purpose and returns, followed by usage advice. Efficient and scannable.

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 lists returned fields. Combined with clear annotations and one parameter, the tool is fully understood.

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% (single boolean parameter fully described). Description adds no additional meaning beyond schema, meeting baseline.

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

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

Description clearly states the action (listing subscriptions) and the resource (caller's active subscriptions), and distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing clear 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?

Discloses rate limits ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and impact ('signal directly affects roadmap'). No contradictions with annotations (all false). Adds context beyond structured fields.

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

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

Description is relatively concise with 4 sentences, each adding information. Front-loaded with purpose. Could be slightly shorter, but 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?

Complete for a feedback tool: covers behavioral traits (rate limits, cost), parameter usage, and what not to do. No output schema needed. Handles all needed context for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value: explains each type (e.g., 'bug = something broke'), advises on message content ('Describe the issue in terms of Pipeworx tools/packs'), and clarifies context 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 the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('team feedback'), and distinguishes from sibling tools (e.g., ask_pipeworx, feedback) by focusing on 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?

Explicitly tells when to use: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also provides clear warnings: 'don't paste the end-user's prompt.'

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

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

Annotations already indicate readOnly and idempotent, but the description adds valuable context: derived from analytics engine, no PII, cached 5min-1h, and return structure (pack, tool, count). No contradiction.

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

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

Well-structured with front-loaded purpose, use cases, and technical notes. Every sentence adds value, though slightly verbose for a simple tool.

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

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

Given no output schema, the description adequately describes return fields, data source, and caching. Lacks exact JSON structure but sufficient for a read-only trend 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 a description for the parameter. The tool description reinforces the window trade-offs beyond the schema, adding rationale for selecting window sizes.

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 returns top tools, top packs, and total call volume, using specific verbs like 'returns' and 'discovering'. It distinguishes from sibling tools like 'discover_tools' by focusing on other AI agents' current usage, not a general tool 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?

Three explicit use cases and explanation of window size trade-offs are provided. Lacks explicit when-not-to-use or alternatives, but context is clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial context beyond these, explaining internal logic (monotonicity violations, partition checks, fill check against live order book) and constraints (Jaccard similarity threshold, placeholder filter). 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 fairly long but well-structured: requirement first, then mode details, behavioral details, response format, and fill check. It is front-loaded with key information. While every sentence adds value, it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (two modes, internal logic, response shape, fill check) and the absence of an output schema, the description provides a remarkably complete account. It details the response structure, fill check behaviors, and even mentions a related sibling tool, leaving minimal ambiguity about what the tool does and 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 description coverage is 100%, but the description enriches parameter understanding with concrete examples (e.g., 'fed-decision-may-2026', 'Fed rate decision'), additional accepted formats (URLs), and usage context that goes beyond the schema's terse descriptions.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket' with specific verb and resource. It explains two modes (single-event and cross-event) which distinguishes its usage scenarios from sibling tools, but does not explicitly differentiate from closely related tools like polymarket_edges or polymarket_fill_risk.

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 requires one of `event` or `topic` and warns against calling with no args. It recommends `event` for specific markets and `topic` for cross-event scanning, and mentions alternative tool polymarket_fill_risk for custom sizing. However, it lacks explicit guidance on when not to use this tool versus other arbitrage-related 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?

The description extensively discloses behavioral traits: model details, filters, caching, diagnostics, and edge computation. Annotations confirm readOnly, openWorld, idempotent, and non-destructive, and the description aligns with 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 a long paragraph that, while detailed, could be broken into sections. It is front-loaded with the main purpose but loses conciseness due to excessive detail.

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

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

With 9 parameters, no output schema, and no nested objects, the description is thorough, covering segments, diagnostics, and knobs. A brief example response would improve completeness.

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

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

Despite 100% schema coverage, the description adds substantial meaning to each parameter, explaining tradeable-edge knobs, slippage context, and per-leg Kelly filters. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies three opportunity segments, distinguishing it from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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 'Built for "what should I bet on today"' and explains the segments and filters. However, it does not explicitly state when not to use this tool compared to alternatives like polymarket_arbitrage.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds extensive context: snapshot mechanism (cache-miss writes), response structure (tracked, expired, snapshot_dates), decay computation from daily closes, and data gaps explanation. Fully discloses behavior beyond annotations.

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

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

Description is lengthy but well-structured: starts with purpose, then details response fields, then limits. Every sentence adds value for understanding the tool's output and behavior. Slightly verbose but appropriate given 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, description thoroughly explains all response components (tracked, expired, snapshot_dates) with field meanings. Also covers limitations, data sources, and decay computation. Complete for a historical telemetry 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?

Both parameters are described in schema (100% coverage). Description adds default values (days=14, window='1wk') and constraints (days max 30, clamp 2-30, window options '24hr|1wk|1mo'), providing meaningful guidance beyond schema.

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

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

Description clearly states the tool's function: tracking edge persistence and decay over time using daily snapshots. It poses a specific question it answers and implicitly distinguishes from the sibling tool 'polymarket_edges' which likely provides current edges.

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

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

Description provides context on when to use (historical edge analysis) and mentions limits (60-day TTL, snapshot gaps), but does not explicitly state when not to use or compare directly with alternatives. The implied use case 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=true, idempotentHint=true, destructiveHint=false, confirming safety. The description adds significant behavioral context: it walks the order book ladder, returns a verdict (clean/degraded/cannot_fill), and warns about forced directional risk from partial fills. 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 longer than ideal but front-loaded with core purpose. It uses clear section headers (SINGLE-MARKET, BASKET) and lists return fields. Every sentence adds value, though some details (e.g., specific return field names) could be more concisely integrated. Still well-structured for an AI agent.

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

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

Despite no output schema, the description fully explains return values for both modes: single-market (top_of_book, vwap_fill_price, slippage_pp, etc.) and basket (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, forced_directional_risk). Parameters are well covered. Usage context and risks are thoroughly explained, making this complete for an AI agent to 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 description coverage is 100%, so each parameter has a schema description. The tool description adds value by explaining the default logic for 'side' in basket mode (auto from partition sum), clarifying 'size_usd' as settlement notional for baskets, and noting clamp range (10–1,000,000). This goes beyond the schema but does not elaborate on all parameters equally.

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 this tool is a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, each with specific inputs and outputs. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risk of partial basket fills turning an arb into an unhedged directional position. However, it does not explicitly state when NOT to use it (e.g., for very small trades), which would improve clarity.

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, idempotent, non-destructive. Description adds detailed behavioral info: computes spreads, returns compatibility_warning for non-equivalent bet shapes, temporal_alignment flag, and skipped counters. No contradictions; fully transparent.

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 paragraphs and emphasis on key details. Front-loaded with purpose. However, slightly verbose; could be trimmed without losing essential info, but the detail is justified given tool 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?

No output schema, so description must explain return fields. It covers leg-by-leg prices, spreads, compatibility_warning, temporal_alignment, and skipped counters. Addresses multiple edge cases (shape mismatch, temporal mismatch, unrelated events). Complete for a complex tool.

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

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

Schema coverage 100% with descriptions. Description adds substantial meaning: explains mode selection, lists all 10 topic shortcuts, gives example values for explicit parameters, and clarifies override behavior. Adds significant value beyond schema.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket. Specific verb 'spread' and resource 'cross-venue comparison.' Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly mentioning both venues and the spread concept.

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: for comparing spreads between two venues. Describes two modes (topic shortcuts and explicit tickers) and warns that pre-mapped topics often yield warnings, guiding appropriate usage. No alternatives mentioned but sufficient for the tool's niche.

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 scoping detail (by identifier) and pairing guidance. 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?

Four sentences, each adding value. Front-loaded with action, no redundant phrases.

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

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

Covers all aspects for a simple tool: retrieval vs listing, scoping, pairing. No output schema needed. Minor gap: return format on missing key not described.

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

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

Schema coverage is 100% with property description. Description reiterates param behavior but adds no new semantic value beyond what schema provides.

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

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

Description explicitly states dual functionality: retrieve value by key or list all keys by omitting key. Clearly distinguishes from sibling tools 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 clear use case (look up stored context) and mentions omitting key for listing. Implicitly contrasts with remember/forget siblings, but lacks explicit 'when not to use'.

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

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

Description states mark_read:true flags events as read, implying a state change, which contradicts the readOnlyHint annotation (true). This is an annotation contradiction, per guidelines scoring 1.

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 four sentences, front-loaded with purpose, no redundancy. Efficiently conveys key information.

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

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

Given no output schema, description explains return fields (source, citation_uri, raw payload) and covers all parameters. Lacks pagination/ordering details, but sufficient for a read list tool.

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

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

Schema coverage is 100%, baseline 3. Description adds examples for type and since, explains mark_read effect, but does not detail limit exact range or unread_only interaction. Adds marginal value beyond schema.

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

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

Description uses specific verb 'Pull' and resource 'fired events from your subscription feed', clearly distinguishing from siblings like list_subscriptions, subscribe, and unsubscribe. No other tool fetches recent alerts.

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

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

Provides context for filtering (type, since) and mentions polling, as well as an alternative HTTP endpoint. However, it does not explicitly state when not to use or compare to other tools.

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

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

The description discloses multi-source fan-out, fallback logic (GDELT to GNews), and soft-failure for USPTO, going beyond annotations which already indicate read-only, idempotent, non-destructive behavior.

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

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

The description is a single dense paragraph that efficiently conveys purpose, sources, parameters, and alternatives. While concise, it could benefit from slight structuring (e.g., bullet points) for even easier scanning.

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

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

Despite lacking an output schema, the description explains the return structure (grouped changes[], total count, citation URIs) and covers edge cases like fallbacks and soft-fails. Together with 100% schema coverage, the tool is fully specified.

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?

Adds significant meaning beyond the input schema: explains `since` accepts both ISO dates and relative shorthand with examples, clarifies `type` is limited to 'company', and describes `value` as ticker or CIK.

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 change feed for a company over a recent window, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and differentiating from 'entity_profile' which returns a static profile.

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

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

Provides example queries and explicitly recommends 'entity_profile' for static information. However, it does not exhaustively cover all cases where this tool should be avoided, such as when only one source type is needed.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: scoping by agent identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) sessions. 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?

Three sentences: first sentence states purpose, second gives usage context, third provides scoping and duration details. Every sentence is necessary and front-loaded with the most important information.

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

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

Given the tool has only 2 simple parameters, no output schema, and clear annotations, the description covers all necessary context: purpose, when to use, scoping, persistence, and companion tools. Nothing 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 descriptions for both key and value. The description adds naming convention examples ('subject_property') and clarifies value as 'any text', but this only slightly expands on the schema's 'Value to store (any text...)'.

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 'Save' and resource 'data the agent will need to reuse later'. It distinguishes from sibling tools 'recall' and 'forget' by mentioning them as companion tools, ensuring the agent knows this is for storage.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It references companion tools for retrieval and deletion, but does not explicitly state when not to use it or what alternatives exist beyond the mentioned siblings.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds that each call cascades through several lookup endpoints internally, and details the return format for each entity type (e.g., ticker+CIK+citation for company; RxCUI+ingredient+citation for drug), beyond what annotations offer.

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 and well-structured: front-loaded with common natural language queries, followed by supported types and return details. Every sentence adds value, with no redundancy.

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

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

For a tool with only 2 parameters and no output schema, the description provides complete context: it explains internal cascading behavior, return structures, and input flexibility, making it fully self-contained 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 substantial meaning: for the 'type' parameter it explains what each type returns; for 'value' it lists acceptable input formats (ticker, CIK, name, brand/generic) with examples, enriching the schema descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It includes specific query patterns ('What's the ticker for...', 'find the CIK for...') and distinguishes itself from sibling tools by being the go-to for name-to-ID resolution.

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,' providing clear guidance on when to invoke. It does not list specific alternatives among siblings, but the instruction is strong and contextually sufficient.

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

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

Annotations already declare the tool as safe (readOnlyHint, idempotentHint). The description adds that it internally calls `ai_visibility_check` for each entity and returns a ranked list with score, confidence, and signal density, providing valuable behavioral detail beyond the annotations.

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

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

The description is four sentences, front-loaded with the main purpose, followed by process, example, and return format. 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 tool's moderate complexity (4 params, no output schema), the description sufficiently explains what it does, how it works (calls another tool), and what it returns (ranked list with scores). It is complete for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds extra meaning: 'First entry treated as the "subject" for narrative; rest are competitors' and provides a concrete example for the `context` parameter. This clarifies intent 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 'Compare AI visibility across multiple entities side-by-side', which is a specific verb and resource. It distinguishes itself from sibling `ai_visibility_check` (single entity) and `compare_entities` (generic comparison).

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

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

The description provides explicit usage context: 'Useful for competitive AI-marketing audits' with a concrete example. It does not explicitly state when not to use it or compare to alternatives, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds key behaviors: fans out across services, partial failures degrade gracefully, bundlephobia may take 5-30s on first call, and sources_failed field lists timeouts. 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 fairly long but front-loaded with purpose. Every sentence adds value, though could be slightly more concise. Still well-structured.

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

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

Given complexity (two services, partial failures, timeout behavior, output structure), the description is thorough, covering return summary, advisory details, and ecosystem limitations. Informs agent well.

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

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

Schema description coverage is 100%, so description adds no new parameter-level detail beyond what schema already provides (scoped packages accepted, version defaults to latest). 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 performs a composite check for npm packages, combining deps.dev and bundlephobia data to answer 'should I add this package?' This distinguishes it from sibling tools which are unrelated.

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

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

Explicitly says to use when agent asks about safety, popularity, or size, and notes NPM-only in v1 with cross-reference to other ecosystems via deps.dev:version.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds that it returns title, summary, URL, and publication date, which is useful but not extensive behavioral context.

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

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

The description is a single concise sentence that front-loads the purpose and output. Every word is meaningful with 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?

Given the simple tool with only 2 parameters, clear annotations, and an output schema, the description is complete enough. It explains the input and output without needing to cover return values.

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 parameters are well-documented. The description adds the 'by keyword' phrasing but does not provide additional meaning beyond the schema.

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

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

The description clearly states it searches spaceflight news articles by keyword and returns specific fields. However, it does not explicitly differentiate from siblings like get_articles or search_within, leaving some ambiguity.

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

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

No explicit guidance on when to use this tool versus alternatives like get_articles or search_within. Usage is implied by the description but not clarified.

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 behavioral details beyond annotations: cap at 200K chars with truncation flag, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and that passages include offsets for verification.

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 efficient and front-loaded. It covers purpose, usage, alternatives, and technical details in two sentences plus a technical detail sentence, 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 lacking an output schema, the description explains what is returned (top-N passages with offsets and similarity scores). It also details the embedding model and windowing. All necessary context for an agent to use the tool is present.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: explains the purpose of 'text' with max char, 'query' with natural-language examples, and 'limit' with default. However, the schema already has descriptions, but the description enriches them.

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 semantic search inside a fetched record, specifying input (text, query) and output (top-N passages with offsets and scores). The title 'Search Within a Source' aligns well. It 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?

The description explicitly says when to use it: 'Use when the record is too big to cram into the prompt.' It also provides alternatives and context, such as pairing with ask_pipeworx_grounded for grounding over relevant passages.

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

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

Annotations indicate idempotent and non-destructive. Description adds important traits: returns subscription id, requires OAuth, SMS cap of 10/day, webhook auto-disable after 10 failures. 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?

Packed with information, front-loaded with purpose. Each sentence adds context; could be slightly more concise but still well-structured.

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

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

Given complexity (3 params, nested objects, enum), description covers all: prerequisites, return value, caps, webhook behavior. No output schema, but return is explained. Complete.

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

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

Schema coverage is 100%, but description enriches with concrete examples for each type, delivery channel constraints, and webhook signing details. Adds significant value beyond schema.

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

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

Clear verb 'Create' and resource 'proactive monitoring subscription to a live-data event stream'. Distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation aspect.

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 requirement for Pipeworx OAuth account, supported types, and delivery channels. References alternative for pulling alerts (recent_alerts). Lacks explicit when-not-to-use but provides sufficient 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns category-bucketed example questions with exact tool+argument shapes, and mentions it draws from a live catalog. 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 comprehensive but not overly verbose. Each sentence serves a purpose, listing examples and use cases. Slightly long but justified by the onboarding role.

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

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

Without an output schema, the description explains the return format (category-bucketed example questions) and mentions how to call meta-tools. 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?

Single optional parameter (topic) is fully described with example values and behavior when omitted. Schema coverage is 100%, and description adds focus area details beyond the schema.

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

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

Description clearly states it is the onboarding entry point to discover what Pipeworx can do, returning example questions. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning as the first tool to use.

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

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

Explicitly says to use this FIRST when you do not know what Pipeworx can do, and mentions how to focus with topic. Could be more prescriptive about when not to use it, but the context effectively guides the agent.

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

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

Annotations show readOnlyHint=false (write), destructiveHint=false, and idempotentHint=true. The description adds important context: ownership enforcement and that the row is deactivated (not deleted) so historical events remain available. 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?

Two sentences, no filler, front-loaded with the core action. 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 single-parameter mutation tool with no output schema, the description covers the operation, ownership constraint, and side effects. It references related tool 'recent_alerts' for completeness.

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

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

The input schema has one parameter 'id' with a description. Schema coverage is 100%, so baseline is 3. The description does not add extra meaning about the parameter beyond what the schema says.

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 'Cancel a subscription by id', which is a specific verb+resource combination. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by indicating it is the cancellation counterpart.

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 mentions ownership enforcement: 'you can only cancel your own subscriptions', which guides when not to use it. It also explains the deactivation behavior and links to recent_alerts, but does not explicitly mention 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 provide safety profile (readOnly, idempotent, non-destructive). Description adds significant behavioral context: returns verdict, structured form, actual value with citation, percent delta, and replaces multiple calls. 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 concise yet comprehensive, front-loading purpose with example queries, then defining scope and outputs. 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 single-parameter tool with no output schema, the description fully explains inputs, outputs, and scope. 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?

Schema covers 100% of parameter. Description adds value with examples of claim formats and explains the parameter's natural-language nature beyond the schema's concise 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 states the tool's purpose: natural-language claim verification against authoritative sources, with specific example queries and a clear distinction from sequential alternatives.

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 whenever the agent needs to check whether something a user said is factually correct' and defines scope (company-financial claims). Lacks explicit when-not-to-use, but scope limitation is clear.

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