spacex

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

Annotations already declare read-only, idempotent, and non-destructive hints, but the description adds crucial context: the default model (Workers AI Llama-3.3-70b) is free, Anthropic calls require a BYO key and directly bill the user, and it details the exact return structure (score, confidence, signals, raw_response + combined view). This goes well 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 two dense sentences, front-loaded with the core purpose and then covering defaults, costs, and output format. Every clause adds information, and there is no redundant or filler content.

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

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

With a moderate 4-parameter schema and no output schema, the description compensates thoroughly: it defines the entity input, explains the default vs. optional model behavior, discloses the API key prerequisite, and specifies the return structure. It also grounds the tool in practical use cases, making it immediately actionable.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by naming the specific default model ('Llama-3.3-70b') and clarifying the cost responsibility for the Anthropic key ('you pay Anthropic directly'). This adds value beyond the schema's generic 'workers-ai' and 'anthropic' strings.

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 a specific verb+resource: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' It clearly states the action, target, and output. It distinguishes from sibling Q&A/research tools by focusing on visibility scoring and mentions concrete use cases like AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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

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

The description gives explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies default behavior and when an API key is needed. However, it does not explicitly state when not to use the tool or point to alternative sibling tools, so it falls short of full when/when-not specification.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: it routes to one of many tools, fills arguments automatically, returns a structured answer with stable citation URIs, works on every tier, and makes 'one fast call.' It does not contradict 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 a single, well-organized block that front-loads the key preference ('PREFER OVER WEB SEARCH') and clear directives ('START HERE'). It includes examples and step-up guidance; every sentence contributes to selection and invocation, though it is longer than strictly necessary.

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

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

The tool is a complex router with no output schema, but the description explains what it returns (structured answer with pipeworx:// citation URIs), when to use it, and how it differs from siblings. It also notes tier availability and speed, making it sufficient for an 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 coverage is 100% because every parameter is described (all aliases for 'question'), and the question parameter is fully documented. The description adds usage examples but no additional syntax or format details beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description defines ask_pipeworx as a router that sends questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with pipeworx:// citations. It explicitly lists supported domains and uses a specific verb ('routes'), clearly distinguishing it from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

It explicitly instructs to prefer this over web search for factual questions, provides trigger phrases ('what is', 'look up', 'find'), and states 'START HERE for most questions.' It names alternatives for when to step up: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions, plus notes how it handles breaking news.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it's a fully working router (no fallback), currently matches ask_pipeworx exactly, and results are compared against the stable router. This explains the experimental nature without contradicting annotations.

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

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

The description is somewhat lengthy but front-loaded with the core identity. Each sentence contributes important context (similarity, active candidates, usage, fallback behavior). Could be tightened, but it's well-structured and information-dense.

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 tool is a complex router with no output schema. The description references 'same response shape' as ask_pipeworx, which provides some context but relies on the agent knowing that sibling tool. It doesn't explicitly describe the return structure or behavior beyond routing. Adequate but could be more 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%, and the schema already describes the 'question' parameter and its aliases in detail. The description does not add parameter semantics beyond stating that arguments are identical to ask_pipeworx, which is redundant given the schema. Baseline of 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, a universal router with the same tools/arguments/response shape, but with experimental routing improvements. It specifies a distinct verb+resource ('ask' with routing) and differentiates from ask_pipeworx by emphasizing its beta/experimental edge.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing.' This tells the agent when to choose this tool over the stable alternative and explains the comparison/merge process, though it doesn't state when not to use it, the positive 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 already indicate read-only, idempotent, non-destructive. Description adds critical context: one extra LLM call cost, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the guarantee of using ONLY tool result content. This goes well beyond annotations and reveals behavior on failure. 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?

Description is dense but every clause carries information: mode, routing, extraction constraint, return structure, refusal reasons, usage contexts, and cost tradeoff. It is front-loaded with the core purpose and structured logically from behavior to usage to cost.

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 explicitly provides the return shape on success and failure modes. It also covers when to use, cost implications, and the grounded extraction guarantee. This is comprehensive for a complex tool with multiple refusal paths.

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 question and aliases fully described in the schema. The description does not add new parameter details beyond saying the tool 'fills arguments' and 'fetches data', which is about internal routing rather than parameter semantics. Baseline 3 is appropriate for full schema coverage.

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

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

Description clearly identifies the tool as a hallucination-resistant answer mode with specific behavior: extracting answers only from tool results. It distinguishes from sibling ask_pipeworx by explicitly stating the same routing but grounded extraction, and mentions the refusal mechanism. Verb-specific and resource-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?

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. Also provides when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to extra cost. This gives clear guidance vs 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?

The description goes far beyond annotations: it details fan-out behavior, resolver contract with match confidence and alternatives, safety short-circuiting, status codes for closed/inactive markets, news fallback handling (GDELT 429s), and cancellation rule risk. It even quantifies response sizes for include_raw. No annotation contradictions; readOnlyHint and idempotentHint align with the read-only research 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 long but well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose and examples. Every section provides valuable operational detail, though it could be more concise by condensing some examples. It is appropriately sized for a complex tool with no output schema.

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, lack of output schema, and rich behavioral nuances, the description covers all critical aspects: input formats, resolution confidence, parent event extraction, news fallback, safety blocking, and resolution-rule risk. An agent can confidently invoke the tool and interpret its results without additional documentation.

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%, providing clear descriptions for market, depth, and include_raw. The description adds value for the market parameter by giving concrete slug/URL/question examples and clarifying that the tool resolves the market. It does not add much for depth or include_raw beyond schema, but the examples for the required parameter justify a score above baseline 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and the output (evidence packet + market-vs-model comparison). It also distinguishes itself from siblings by focusing on single-bet research and explicitly giving use cases like 'should I bet on X'.

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 examples ('Use for "should I bet on X"...') and explains the mechanism of resolving and classifying the bet. It does not name alternative sibling tools or explicit when-not-to-use, but the context signals and siblings imply this is the go-to for single-market research. The lack of exclusions keeps it just shy of a 5.

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

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

Annotations cover readOnly and non-destructive nature, but description adds significant behavioral context: source systems (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, paired data output, and citation URIs. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. Front-loaded with trigger phrases, then behavior, type-specific details, and output format. No fluff or repetition.

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

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

Given no output schema, the description effectively explains return structure (paired data + citation URIs), sorting, and covers both entity types. Includes performance benefit (replaces 8-15 lookups) and edge cases (fiscal year handling). Complete for a tool with only 2 parameters.

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

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

Schema coverage is 100%, but description enriches parameter meaning substantially: explains what data each type pulls (10-K financials vs adverse-event counts), expected value formats (tickers/CIKs vs drug names), and result sorting behavior. This goes beyond basic 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 with specific verbs ('Compare', 'rank', 'head to head') and resource scope (2-5 companies or drugs). It distinguishes from sequential single-pack lookups and specifies data sources (SEC EDGAR/XBRL, FAERS).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance and an alternative. Also differentiates between type='company' and type='drug' 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=true and idempotentHint=true, but the description adds substantial behavioral context: account/auth requirement, paid depth tier, gap[] handling with 'never invented', contradictions[] for standard/thorough, semantic excerpting vs head-truncation, timing (15-90s), and resolvable citation_uri behavior. 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 long but front-loaded with the critical account warning and densely packs distinct info per sentence. Could be slightly streamlined, but given the tool's complexity (parallel decomposition, depth modes, citation details, exclusions) the length is largely justified.

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 specifies the return payload (findings packet with verbatim evidence, confidence, source, fetched_at, citation), gap[]/contradictions[] behavior, timing, citation resolvability, and semantic excerpting. It leaves no major operational question unanswered.

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 enum descriptions are present, but the description enriches semantics: explains that 'broad/multi-part' questions are fine, each depth level's facet counts, the paid requirement for 'thorough', and the iterative hop behavior. This goes beyond the schema's bare enum 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 states a specific verb ('Grounded multi-source research') with a clear resource scope ('Pipeworx's 1455 STRUCTURED data sources... NOT open-web search'), and distinguishes from sibling tools by explicitly naming alternatives ('For a single lookup use ask_pipeworx... prefer ask_pipeworx'). It is unambiguous what the tool does and how it differs.

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 ('Best for broad/multi-part questions over structured data'), when-not-to-use with alternatives ('For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even addresses account tier restrictions ('If you are not signed in, use ask_pipeworx instead'). This gives the agent clear selection 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 already declare readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral detail: it returns top-N tools with names, descriptions, and full input schemas with curated examples, and that results are ready to call directly without a second schema lookup. This goes beyond annotations by explaining the exact output behavior and pragmatic value.

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: the core purpose comes first, followed by usage context, then return behavior, then a directive. The domain list is lengthy but serves a purpose by showing the breadth of searchable areas. It is slightly verbose compared to an ideal two-sentence description, but every sentence adds value and it is easy to scan.

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

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

With no output schema, the description carries the burden of explaining what the tool returns, which it does clearly ('Returns the top-N most relevant tools... each result is ready to call directly'). It covers all essential aspects: how to invoke it, what domains it covers, what the output looks like, and when to call it first. This is complete for a discovery tool with rich annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that 'query' is a natural language description, but it does not add meaning beyond what the schema already provides. Aliases (q, task, search, description) are documented in the schema, and the description does not clarify when to use one over another, but that is acceptable given full schema coverage.

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

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

The description opens with 'Find tools by describing the data or task', giving a specific verb and resource. It clearly distinguishes the tool as a discovery mechanism from siblings by enumerating the domains it covers (SEC filings, FDA drugs, FRED, etc.) and stating it returns top-N relevant tools. This is unambiguous and not a tautology.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This tells the agent when to invoke it and implies when not to (when a single specific answer is needed). It provides clear context among the many 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 declare read-only and idempotent behavior, and the description builds on this by revealing a soft-fail for the USPTO PatentsView API (sunset May 2025) and the GDELT→GNews fallback for news. It also details the parallel fan-out across multiple data sources and the exact return fields, adding valuable behavioral context 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 longer than average but earns its length: most sentences deliver distinct information (examples, use-case, components, return fields, input constraints). It is front-loaded with user-facing examples and ends with a critical caveat about names, making it well-structured for an AI agent scanning for relevance.

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

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

With no output schema, the description thoroughly enumerates what is returned: cik, company_name, recent_filings (with URI format), fundamentals (10-K fields, order), patents, news, and LEI. It also notes limitations like 'names not supported' and the patent API sunset, giving the agent a complete picture of the tool's capabilities and edge cases.

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 both parameters have descriptions, but the description adds practical input semantics with examples ('Pass ticker "AAPL" or zero-padded CIK "0000320193"') and clarifies the 'type' enum only supports 'company'. This goes beyond the schema's fields.

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

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

The description opens with concrete example queries and then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses a specific verb ('profile') and resource ('US public company'), and distinguishes itself from sibling tools by explicitly advising preference over chaining multiple lookups.

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

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

The description is explicit about when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear alternative and prerequisite: 'names not supported (use resolve_entity first if you only have a name).'

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, idempotentHint=true, and readOnlyHint=false, so the description's 'Delete' aligns with expectations. It adds context about sensitive data and complementary tools, but doesn't cover outcomes like permanent removal or behavior on missing keys. 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?

Three short sentences that front-load the core action, then provide use cases and related tools. No wasted words; every sentence serves a clear purpose.

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

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

For a simple one-parameter tool with strong annotations and sibling context, the description is complete. It explains the function, when to use it, and how it relates to remember and recall, leaving no significant gaps.

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

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

The schema provides 100% coverage for the single 'key' parameter, including description and example. The description merely says 'by key', adding no meaningful enrichment beyond what the schema already 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 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings like remember and recall by focusing on deletion of stored memories.

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 use cases are given: stale context, task done, and clearing sensitive data. It also mentions pairing with remember and recall, though it doesn't explicitly state when not to use the tool or contrast with 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 that the tool 'Fetches the page, extracts title/description/key links' and 'emits the standard llms.txt markdown format', adding behavioral context beyond the annotations' readOnlyHint and idempotentHint. This informs the agent about network fetching and output format, which is valuable.

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 sentences, front-loaded with the primary action, and every sentence earns its place: the first states the core function, the second explains the process, and the third lists use cases. No wasted words.

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

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

Despite having no output schema, the description adequately explains the return value ('Output is a single text blob ready to drop at site-root/llms.txt') and the internal process. It is sufficiently complete for a simple read-only tool, though it does not cover edge cases like invalid URLs.

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 already provides detailed descriptions for both parameters (url and max_links) with 100% coverage. The description reinforces the 'any URL' aspect but does not add additional parameter semantics beyond what the schema already states, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It uses a specific verb ('Generate') and resource ('llms.txt'), and distinguishes itself from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation rather than auditing.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to use. It does not explicitly mention when-not-to-use or name alternatives, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context by noting that data is 'derived from recent crewed SpaceX launches,' which hints at data recency/scope. It does not contradict annotations.

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

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

The description is three short sentences, all informative and front-loaded with the core purpose. Every sentence earns its place: what it does, what it returns, and the data source caveat.

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 a single optional parameter, an output schema, and strong annotations, the description is sufficiently complete. It covers the purpose, return fields, and a data-scope caveat. No critical information is missing for an agent to select and invoke it 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%: the limit parameter is already described in the schema (default 20, max 50). The description adds no additional parameter-level detail, which is acceptable given the high schema coverage, but it also doesn't provide any extra nuance about limit behavior.

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 (List) and resource (astronauts on SpaceX Crew Dragon missions), and specifies the exact scope (flown or assigned). It also lists the return fields, which distinguishes it from sibling launch tools like get_latest_launch or get_past_launches.

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

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

The description gives a clear context for when to use the tool (when you need crew member info for Crew Dragon missions) and implicitly differentiates it from launch-focused siblings. However, it does not explicitly state when not to use it or mention alternative tools for other crew/capsule types.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds return field details but no additional behavioral traits such as potential null results or dynamic nature of 'latest'.

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

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

Two sentences, front-loaded with the action, followed by a concise list of return fields. 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?

For a zero-parameter, read-only tool with an output schema and annotations, the description provides sufficient detail about what is returned. It is complete within the context of structured data.

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 tool has zero parameters, so the baseline is 4. The description doesn't need to explain any parameters and none are present.

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

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

The description uses a specific verb 'Get' with a clear resource 'most recent SpaceX launch', distinguishing it from sibling tools like get_next_launch and get_past_launches. It clearly states what the tool returns without 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?

The description implies usage for retrieving the latest launch but does not explicitly contrast with get_next_launch or get_past_launches. It provides clear context for the 'most recent' specific launch, yet lacks exclusionary or alternative 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by noting that the scheduled date is in UTC and may be TBD, alerting the agent to potential data uncertainty.

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 short sentences that front-load the action and results, with no redundant words. Every word earns its place.

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

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

For a parameterless, read-only tool with an output schema present, the description fully captures scope, return content, and a key data-quality caveat. No other behavioral expectations are needed.

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 tool has zero parameters, so there is nothing to add beyond the schema. Baseline 4 applies, as no parameter description is needed.

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 'Get the next upcoming SpaceX launch' with a specific verb and resource, and enumerates the returned fields (launch name, date, mission details, rocket, pad). This clearly distinguishes it from sibling tools like get_latest_launch and get_past_launches.

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 retrieving the next upcoming launch, but it does not explicitly contrast with alternative sibling tools (e.g., get_latest_launch or get_past_launches). No usage conditions or exclusions are provided, leaving the when-to-use guidance implicit.

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, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations by specifying the sorting order (descending) and the exact fields returned (name, date UTC, status, success), which is meaningful for an agent.

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, front-loaded with the main action, and contains zero fluff. Every word adds value: the action, the sorting, and the return fields are all stated efficiently.

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

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

For a simple tool with one optional parameter and an output schema present, the description is complete. It covers the tool's purpose, scope (recent past), ordering, and return fields, and the annotations cover safety concerns, leaving no major gaps.

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

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

The input schema has 100% coverage for the single 'limit' parameter, with a clear description of default and max. The description does not add anything about the parameter, so it relies on the schema as expected; 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 'Get recent past SpaceX launches sorted by date descending' with a specific verb and resource. It also distinguishes itself from sibling tools like get_latest_launch and get_next_launch by focusing on 'past launches' and describing the return fields.

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

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

The description provides clear context: it returns recent past launches, sorted descending, with specific fields. While it doesn't explicitly name alternatives or exclusions, the wording implies this is for historical/recent launches rather than next/latest, which is sufficient for a simple read-only 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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a strong safety profile. The description adds value by detailing the exact return fields (name, family, reusability, etc.), which informs the agent about the data shape beyond the annotations. No contradictions found.

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 of concise, high-signal content. Every word adds value: it identifies the resource, gives examples, and lists output fields. No filler or 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 (no parameters), rich annotations, and the presence of an output schema (not shown but indicated), the description fully covers the necessary information. It includes the specific data fields, making the tool's behavior clear and self-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?

The tool has zero parameters, so the baseline is 4. The description clearly states what the tool returns without needing parameter-level explanations, as there is nothing to configure.

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 with a specific verb ('List') and resource ('SpaceX rocket configurations'). It includes concrete examples (Falcon 1, Falcon 9, etc.) that distinguish it from sibling tools like get_latest_launch or get_past_launches, which focus on launches rather than rocket configurations.

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 the tool is for retrieving rocket configuration data, not launch events, and names the specific data fields returned. However, it does not explicitly mention when to use this tool over alternatives or provide exclusions, though the scope is clear from the 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, openWorldHint, idempotentHint, and destructiveHint. The description adds source, sorting, and return fields, which is useful but does not disclose potential limitations like pagination, rate limits, or refresh behavior. Given annotations cover the safety profile, this is adequate but not rich.

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

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

Two concise sentences: the first front-loads purpose and source, the second lists return fields. No unnecessary words or repetition of schema details.

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 optional parameter, annotations, and an output schema, the description is complete. It covers purpose, data source, sorting, and return fields, leaving no significant gaps for an 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 coverage is 100% for the single optional `limit` parameter, including default and max values in the schema. The description does not mention `limit` at all, so it adds no parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

Clearly states 'Get live Starlink satellites' with specific source (CelesTrak), sorting by epoch, and lists return fields. Unambiguously distinct from sibling tools like get_crew, get_rockets, and launch tools.

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

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

The description implies usage for live Starlink satellite data from the public catalog, which is clear context. However, it does not explicitly mention alternatives or exclusions, though no sibling tool overlaps with this purpose.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds behavioral context by specifying the return fields (id, type, params, etc.) and scoping to active subscriptions. 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 two sentences: the first states the action and return fields, the second explains use cases. Every sentence earns its place, and it is front-loaded with the 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 tool's simplicity (one optional parameter, no output schema) and strong annotations, the description is complete. It covers the scope (caller's subscriptions), return fields, and practical use cases. It doesn't mention include_inactive, but the schema fully covers that.

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

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

Schema coverage is 100% for the single optional parameter include_inactive, which has a clear description. The tool description does not add any additional information about this parameter, so it relies entirely on the schema. Baseline of 3 is appropriate given perfect schema coverage.

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

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

The description uses the verb 'List' with the specific resource 'the caller's active subscriptions,' clearly stating what the tool does. It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on read-only listing. It also lists the exact return fields, leaving no 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?

The description explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for the tool's role in the subscription workflow. However, it doesn't explicitly name alternative tools like subscribe/unsubscribe, though the context implies 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 only set all hints to false, providing no side-effect information. The description compensates by disclosing the claim_token flow, daily rate limit of 5 per identifier, that it's free, doesn't count against tool-call quota, and that the team reads digests daily. 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 long but every section earns its place: purpose, usage scenarios, scope restriction, token mechanism, rate limit, and cost. It's front-loaded with the main purpose and structured sequentially. Slightly verbose but justified by 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?

With no output schema, the description covers all essential aspects: what the tool does, when to use it, what to write, how the claim_token works, and limitations. It even explains why reporting other servers' issues here is counterproductive. This is fully complete for an agent to invoke it 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 already covers all four parameters with detailed descriptions, giving a baseline of 3. The description adds practical usage semantics for `message` ('describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and for `claim_token` (pass it later to read the resolution), which goes beyond the schema's basic descriptions.

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

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

The description explicitly states 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb and resource. It also enumerates feedback types (bug, feature/data_gap, praise) and is clearly distinct from sibling tools like ask_pipeworx or research tools.

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

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

The description gives explicit when-to-use guidance: '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).' It also provides a clear exclusion: 'if the tool came from a different MCP server in your client... file it with that server instead.'

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context: cached 5min-1h, derived from CF analytics-engine, no PII, and output shape (pack, tool, count). This gives agents accurate expectations about freshness, privacy, and return format 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?

Front-loaded with the core purpose and output, then structured into a compact 'Useful for' list, followed by a concise note on data source and caching. Every sentence contributes value; no filler or 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?

With one optional parameter and no output schema, the description compensates fully by specifying what is returned (top tools, top packs, total call volume), the output format (pack, tool, count), the caching behavior, and the absence of PII. An agent would know how to invoke it 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 description covers 100% of the single parameter, including enum values and the semantic distinction between shorter windows (hot right now) and longer windows (steady-state demand). The tool description merely restates the window options without adding new meaning, so the baseline 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 opens with a specific, substantive statement of what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This verb+resource+scope clearly differentiates it from sibling tools like discover_tools and ask_pipeworx, which focus on discovery or direct Q&A, not aggregate usage trends.

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

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

Provides three explicit use cases (discovering hot data sources, confirming a canonical tool before asking, and checking alignment with common agent needs). While it doesn't name specific alternatives or state when not to use, the 'Useful for' list constitutes clear contextual guidance, earning a 4 rather than a 5.

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

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

Annotations declare readOnly/openWorld/idempotent, so the bar is lower, but the description adds extensive behavioral details: the >3pp signal threshold, the Jaccard similarity anchor (≥0.30), the placeholder filter (>20% returns null), and the fill check with 'realizable_edge_pp ≤ 0 means do not trade it'. No contradictions with annotations.

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

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

The description is long but well-structured with uppercase section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose/mode guidance. Every paragraph carries non-redundant detail, though the repeated example slugs 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?

No output schema exists, but the description explicitly details response structure: opportunities[] with fields, partition_check object, and fill_check pricing details. It covers modes, filters, edge cases, and a pointer to a sibling tool, making it complete for a complex analysis tool.

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

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

Schema coverage is 100% and already describes both parameters with examples. The description goes beyond by explaining what each mode does internally: event walks child markets and computes partition checks, topic flattens related events and runs the comparator on the union. This adds meaningful behavioral 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', a specific verb+resource+scope statement. It clearly distinguishes between event mode, topic mode, and default trending_scan, and mentions polymarket_fill_risk as a sibling alternative.

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 recommends event mode for a specific market, topic mode for cross-event scanning, and explains the no-arg default. It names polymarket_fill_risk for custom sizing, but does not contrast with all siblings like polymarket_edges. Overall, clear context and some alternative guidance.

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

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

The description discloses far beyond annotations: caching behavior (1h KV), response structure, diagnostics for empty segments, tradeable-edge knobs, edge erosion warnings, and design rarity. It explains why certain signals are excluded and how filters interact, providing deep behavioral transparency.

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

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

The description is long and dense, but well-organized into clear sections (model families, knobs, response structure). Purpose is front-loaded. While it could be trimmed, every sentence carries technical substance for a complex 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?

This is a complex tool with 9 parameters and no output schema, yet the description covers all essential aspects: response segments, per-opportunity fields, diagnostics, caching, Fed exclusion rationale, and knob interactions. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100% with detailed descriptions, and the tool description adds extra semantic context: it groups knobs as 'TRADEABLE-EDGE KNOBS', explains how min_partition_leg_kelly applies to per-leg Kelly rather than parent-level, and clarifies why min_kelly doesn't filter partition arbs. This enriches parameter understanding beyond the schema.

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

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

The description opens with a specific verb ('Scan') and resource ('top Polymarket markets'), clearly stating it returns opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling Polymarket tools by focusing on edge discovery for 'what should I bet on today'.

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

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

Provides clear context for when to use the tool (daily bet discovery) and explains knobs that shape usage, but does not explicitly name sibling tools as alternatives or state when-not-to-use. Internal caveats (e.g., Fed signal unreliability) give exclusion guidance within the tool's scope.

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

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

Beyond annotations (readOnly, idempotent), the description discloses critical behavioral traits: snapshots are only written on cache-miss so gaps mean 'nobody scanned that day,' history is bounded by a 60-day TTL, and decay numbers come from daily closes rather than intraday data. This adds substantial context 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 compact and well-structured: it opens with purpose, then explains arguments, response structure, and limitations in distinct sections. Every sentence carries information density, using clear labels for fields and outputs.

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 absence of an output schema, the description thoroughly defines the response fields (tracked, expired, snapshot_dates) with their semantics and caveats. It also covers data availability and computation methodology, making the tool fully comprehensible.

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 already provides complete descriptions for both parameters (days, window) with 100% coverage, so the baseline is 3. The description mostly repeats schema details (default, max) and adds the phrase 'snapshot family' for window, but does not add significant new meaning.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical snapshots and evolution rather than 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?

The description conveys a clear use case (comparing fresh vs. old edges, understanding decay) and references polymarket_edges as the data source. It does not explicitly name alternative tools or provide exclusions, but the context strongly implies when this tool is appropriate.

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 the readOnly/idempotent annotations, the description details mode-specific behavior (walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict), basket partial-fill risk, and forced_directional_risk. This adds significant context about what the tool computes and warns about unhedged positions.

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 every sentence earns its place—it covers two modes, parameter defaults, output fields, and risk rationale without redundancy. The first sentence states the core purpose, and the rest is dense but 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?

With no output schema, the description lists all key return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, thin_legs, max_clean_notional_usd, forced_directional_risk) and explains the semantics of clean/degraded/cannot_fill. Combined with annotations and schema, the description fully equips an agent to use this tool.

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

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

Despite 100% schema coverage, the description enriches parameter meaning: size_usd is 'max spend on buys, target proceeds on sells' for single-market but 'settlement notional' for baskets; side default is 'auto from partition sum'; market/event select distinct modes. This goes well beyond the schema's basic descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this from sibling arb/edge tools by explaining it's a pre-trade fill-risk assessment, not an arb finder or edge scanner.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' giving clear when-to-use guidance and naming the alternative tools it complements. It also implies exclusions for smaller trades.

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?

Despite annotations already indicating safe read-only, idempotent behavior, the description adds rich behavioral context: compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. It explains edge cases such as non-equivalent bet shapes and unrelated events, which are crucial for correct interpretation and go far 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 long but structured with clear sections and uppercase labels. Every sentence carries operational value, but the density might be slightly overwhelming; a more compact summary could improve scannability. However, it remains organized and purposeful.

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

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

There is no output schema, so the description takes on the burden of explaining return values. It covers the response shape (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and potentially complex conditions (skipped_cross_type/subtype). This is complete for a tool of this complexity.

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

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

The schema already has 100% coverage with descriptions for each parameter. The description adds meaning by explaining the 'topic' shortcut set, the override behavior of kalshi_event_ticker and polymarket_event_slug, and how these interact. This goes beyond the schema's per-parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes the tool from siblings like polymarket_arbitrage or polymarket_edges, which likely focus on other cross-venue or edge concepts. The two modes further specify exactly what the tool does.

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

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

The description explains two modes ('topic' vs explicit ticker/slug) and when each is appropriate, including the list of pre-mapped shortcuts. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' setting expectations for when to use or avoid certain inputs. However, it does not explicitly name alternative tools or state 'use this instead of X,' so some exclusion guidance is 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 establish safety (readOnlyHint=true, destructiveHint=false). The description adds valuable context about scoping ('Scoped to your identifier') and the omit-key-to-list behavior, enriching the agent's understanding without contradicting annotations.

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

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

Three sentences front-load the core action, then provide use case, scoping, and companion tools. Every sentence earns its place with no filler, making it both concise and structured.

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

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

For a simple tool with one optional parameter, complete schema coverage, and strong safety annotations, the description covers purpose, usage, and scoping thoroughly. The only gap is unspecified behavior for missing keys, which is not critical for tool selection or 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% and the property description already explains 'Memory key to retrieve (omit to list all keys)'. The description's key-related text mirrors this, adding no new semantic 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?

Uses specific verbs 'Retrieve' and 'list' with a clear resource ('value previously saved via remember'). Explicitly distinguishes itself from sibling tools by tying functionality to the remember/forget memory system, making it unmistakable which tool this is.

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 an explicit use case: 'look up context the agent stored earlier... without re-deriving it from scratch' and names companion tools (remember, forget). However, it does not explicitly state when not to use the tool or offer alternative tools, so it falls short of a 5.

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

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

The description states 'Set mark_read:true to flag returned events read,' a state-changing side effect. This contradicts the annotation readOnlyHint:true, which declares the tool read-only. Even though the description discloses the behavior accurately, the annotation conflict forces a score of 1 per the rules.

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 purpose, then filters and alternative access. No unnecessary detail or repetition; 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?

With no output schema, the description explains return fields (source, citation_uri, raw event payload) and read-tracking behavior, plus provides an HTTP alternative. Minor omissions like empty-response behavior or interaction between unread_only and mark_read are acceptable given the tool's simplicity.

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

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

Schema covers all 5 parameters with descriptions, but the prose adds meaningful context: explains that since filters by fired_at time, and that mark_read causes returned events to be marked read so subsequent calls return only newer ones. This goes beyond the schema's basic type/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 opens with 'Pull fired events from your subscription feed' — a specific verb and resource. It clearly differentiates from siblings like list_subscriptions by focusing on fired alerts rather than subscription management, and enumerates returned fields.

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

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

Provides clear usage context: 'Polls work fine' and mentions the same feed is available via HTTP for scripts/dashboards. It doesn't explicitly exclude sibling tools or state 'when not to use,' but the polling and read-tracking guidance gives practical direction.

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?

Despite annotations declaring readOnly/openWorld/idempotent, the description adds meaningful behavioral detail: it documents fallback source behavior under rate limiting, the PatentsView API sunset soft-fail, and the exact return shape (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

The description is dense but well-organized, using lists and semicolons to pack source details, parameter formats, and return structure into a single paragraph. Every sentence adds new operational information, though it's on the longer side for a quick scan.

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

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

With no output schema, the description fully specifies the return contract (grouped changes, count, URIs) and explains the tool's limitations and fallback behavior. It also provides parameter usage examples, making it a self-contained guide for a complex multi-source 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?

All three parameters are already described in the schema (100% coverage), but the description enriches meaning by explaining 'since' formats with examples (ISO vs relative) and clarifying that 'value' accepts either ticker or CIK. This goes beyond the schema's basic descriptions.

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

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

The description opens with concrete user intents and explicitly states it returns a change feed for a company within a time window in one parallel call. It also names the sibling entity_profile as the alternative for static profiles, distinguishing it clearly.

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 contrasts with entity_profile ('Use entity_profile instead when you want the static profile...') and tells users the query intent, while also describing the fallback chains (GDELT→GNews, USPTO soft-fail). This gives clear guidance on when this tool is appropriate.

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 idempotent and destructive hints, and the description adds behavioral context beyond them: memory scoped by identifier, and persistence duration differences for authenticated vs anonymous sessions. This enriches the agent's understanding without contradicting structured metadata.

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 sentences with a clear front-loaded purpose, followed by usage guidance and memory mechanics. Every sentence earns its place with no filler or repetition.

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

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

For a simple 2-parameter write tool with thorough annotations and full schema coverage, the description covers purpose, usage, persistence behavior, and sibling relationships. No critical context is missing, making it complete 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?

The input schema covers 100% of parameters with clear descriptions and examples for both key and value. The description does not add significant parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Save' with a clear resource ('data the agent will need to reuse later') and explicitly distinguishes from sibling tools by naming recall and forget as companions. This makes the tool's purpose unambiguous and well-differentiated.

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

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

The description gives explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also directs pairing with recall and forget, clearly implying alternatives for retrieval and deletion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses internal cascading through multiple lookup endpoints, graceful degradation of LEI/FIGI when upstream sources are unavailable, and explicit handling of unresolved identifiers via an 'unresolved' field. This adds valuable context not covered by annotations.

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

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

The description is long but well-structured with a purpose statement, example phrasings, supported types, and behavioral details. It is front-loaded with the core purpose, but the initial list of example queries is somewhat verbose and 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 the absence of an output schema, the description does an excellent job explaining expected return content: it lists the identifiers, sources, ownership info, and the unresolved field. It also covers input types and degradation behavior, making it complete 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?

The schema already covers both parameters with 100% coverage, including enum values and input examples. The description largely repeats this info (e.g., 'accepts ticker, CIK, or company name'), adding little beyond what the schema provides, so a baseline score of 3 holds.

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/official identifiers required by other tools, using concrete example queries. It specifies supported types (company, drug) and the exact identifiers returned, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description gives an explicit usage condition: 'Use FIRST whenever you have a name but need an ID.' It also implies this tool replaces 2-3 manual lookups, but it does not explicitly name alternatives or state when not to use it, so a 4 is appropriate.

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, lowering the bar. The description adds valuable behavioral context: it reveals the tool internally probes each entity with ai_visibility_check (multiple sub-calls), ranks by score, and returns confidence and signal density fields. This is consistent with annotations; 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?

Three sentences, front-loaded with the core action, then method, then use case. No wasted words; the example quote adds practical intuition without padding.

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 specifies the return format (ranked list with score, confidence, signal density). It covers the multi-probe behavior, use case, and key constraints via schema. The annotations cover safety, making this a complete description for a moderately complex tool.

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

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

Schema coverage is 100% with detailed per-param descriptions (models supported values, _apiKey usage, context disambiguation, entities 2-8 with first as subject). The description adds no further parameter-specific nuance beyond reinforcing 'brand + N competitors' and the output's signal density, which is return-output info; 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 opens with a specific verb ('Compare') and resource ('AI visibility across multiple entities'), immediately distinguishing it from single-entity sibling ai_visibility_check and generic compare_entities. It further specifies ranking, competitive audit use case, and returning per-entity scores, making the tool's unique role clear.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and clarifies the multi-entity context ('your brand + N competitors'). It references ai_visibility_check as the underlying probe, implying it is the single-entity alternative, but does not explicitly state when-not-to-use conditions (e.g., 'for one entity, use ai_visibility_check instead').

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

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

Beyond the annotations, the description discloses important behavioral traits: it fans out across multiple services, mentions latency ('bundlephobia's first measurement on a new version can take 5-30s'), and explains partial failure degradation ('sources_failed will list it if it times out, the rest still returns'). 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 dense but well-structured, opening with the core purpose and each sentence adding a distinct detail (output fields, ecosystem scope, failure handling). There is minimal redundancy, and 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?

Since there is no output schema, the description compensates by enumerating the exact return fields ('summary block... per-advisory detail, links, and a list of recent alternative versions'). It also covers partial failure and latency, making it complete for a complex composite tool.

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

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

The schema already fully documents both parameters (package and version) with descriptions covering scoped packages and default version behavior. The description adds no significant parameter-level meaning beyond what the schema provides, so a 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 'should I add this npm package to my project' and enumerates the data sources and metrics. It distinguishes itself from siblings by explicitly naming the NPM-only scope and directing other ecosystems to a separate path.

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 is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a clear exclusion for non-NPM ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version 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 already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with 500-char overlapping windows, and has a 200K char cap with truncation flagged. 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 dense but every sentence earns its place. It front-loads the primary purpose, then covers benefits, pairing, technical mechanism, and limits. At roughly 100 words, it is appropriately sized for the tool's complexity without redundancy.

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

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

For a 3-parameter tool with no output schema, the description covers everything needed: purpose, usage scenario, return format (top-N passages with offsets and scores), algorithmic details, and input limits. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces parameter meaning ('Pass the text you already pulled... plus a natural-language query') but does not add significant information beyond the schema's existing descriptions for text, query, and limit. The truncation/flagging behavior is useful context but is more behavioral than parameter-specific.

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 a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by emphasizing the input is user-supplied text, not a PipeWorx query, and it explicitly differentiates from ask_pipeworx_grounded by noting it operates on a passage level.

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

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

The description gives an explicit use case: 'Use when the record is too big to cram into the prompt.' It also names a complementary sibling (ask_pipeworx_grounded) and explains the workflow: fetch with the gateway, then ground over passages. This provides clear when-to-use guidance and alternatives.

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

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

The description richly discloses behavioral traits beyond the annotations: OAuth requirement, always-on feed with pull methods, phone verification, SMS cap, webhook signing secret returned once, and auto-disabling after 10 consecutive failures. No contradictions with annotations.

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

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

The description is long but every sentence is information-dense and contributes to understanding. It is front-loaded with the purpose, then requirements, types, and delivery details. Could be slightly better structured with bullets, but remains efficient and readable.

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

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

Given the tool's complexity (multiple types, delivery channels, account requirements), the description is remarkably complete. It covers return value, subscription id, feed access, delivery channel options, verification requirements, and failure behavior, leaving little ambiguity.

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

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

Despite 100% schema coverage, the description adds substantial meaning with concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topics, fred_series series_id), and detailed constraints for delivery parameters like SMS verification and webhook HMAC signing. This greatly exceeds baseline.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and notes 'Returns the new subscription id.' This specific verb+resource pair distinguishes it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context: requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels. It does not explicitly mention when not to use it or contrast with alternatives, but the context is sufficient for most cases.

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

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

The description discloses the return format (category-bucketed example questions with associated tool/argument shapes) and the fact that it draws from a live catalog of thousands of tools. This goes beyond the annotations (readOnly, openWorld, idempotent) by explaining what the output will look like and how the tool behaves, filling the gap since no output schema is provided.

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?

Although the description is lengthy, it is densely packed with useful information. It opens with natural-language example queries, then explains purpose, output, parameters, and usage context. Every sentence earns its place; it is well-structured for an onboarding 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?

With no output schema, the description fully covers what the agent can expect: category buckets, per-question tool and argument shapes, and live catalog sourcing. It also provides complete usage context including optional topic filtering and the recommendation to use it first. No critical information appears 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?

The description adds significant meaning beyond the schema: it lists example focus areas and explains that omitting `topic` yields a cross-category spread, while passing it focuses the results. This gives the agent practical guidance on how to use the parameter, not just what it is.

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

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

The description clearly states the tool is the onboarding entry point for a newly connected agent, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings (e.g., discover_tools, ask_pipeworx) by framing it as the 'FIRST' step for understanding Pipeworx's capabilities.

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 is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains when to call with no arguments vs. passing a `topic`, and mentions that it helps learn how to call other meta-tools. This gives clear context and directs the agent away from using it when specific knowledge already exists.

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 ownership enforcement, deactivation (not deletion), and preservation of historical events. These details go beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and add valuable behavioral context about side effects and data retention.

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

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

Two concise sentences with front-loaded action and no fluff. Every sentence delivers meaningful information: the primary action and the ownership/retention caveats.

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

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

For a simple one-parameter tool with strong annotations, the description fully covers behavior, ownership, and impact on data. No output schema is needed. Complete for agent 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 provides 100% coverage with a clear description of 'id' as 'Subscription id (uuid) returned by subscribe.' The description repeats 'by id' but adds no new parameter semantics beyond 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?

Description is a specific verb+resource: 'Cancel a subscription by id.' It clearly states the operation and differentiates from subscribe by focusing on cancellation. The ownership enforcement adds specificity.

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: you can only cancel your own subscriptions. Contrasts with recent_alerts by noting the row is deactivated not deleted, so historical events remain available. This gives clear context on the effect and relationship to alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds critical behavioral detail: the distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found), plus the warning not to treat 'could_not_verify' as evidence. It also discloses the fallback pipeline behavior and return structure, far exceeding 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?

The description is fairly long but each sentence earns its place: trigger examples, use case, routing, return format, and crucial error semantics. It is front-loaded with the most recognizable trigger phrases, making it easy to match. Slightly verbose but appropriate 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?

With no output schema, the description carries the burden of explaining return values, which it does fully: lists the verdicts, mentions the 'grounded or structured actual value with pipeworx:// citation, and reasoning'. It also explains the two distinct failure modes, covering the complete behavior for all plausible inputs. This is a complete description 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%, and both parameters are already described in detail in the input schema. The description does not add substantial new semantics beyond what the schema states; it merely references tolerance in passing. This fits the baseline of 3 for high schema coverage.

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

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

The description opens with natural-language trigger phrases and explicitly states it performs 'natural-language claim verification against authoritative sources'. It clearly distinguishes the tool from siblings by focusing on fact-checking with a verdict output, and even notes it replaces 4–6 sequential calls, making its scope 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?

It provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines two routing paths (company-financial vs. other claims), giving concrete context. However, it does not explicitly name alternative tools or give when-not-to-use exclusions, stopping short of a 5.

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