iplookup

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 valuable behavioral context beyond annotations: it explains the free vs. paid billing model ('pass `_apiKey` to also probe Anthropic (BYO key — you pay Anthropic directly)') and describes the exact return shape (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond just repeating the annotation hints.

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 core action in the first sentence, and each subsequent sentence adds necessary detail (default model/cost, return format, use cases) with zero filler. It is tightly structured and 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?

The tool probes external LLMs and has no output schema, so the description must explain the return format, which it does clearly. It also covers the cost model and use cases. It lacks explicit failure/rate-limit notes, but for a read-only, non-destructive tool with good annotations and a clear return shape, the description is adequately complete.

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

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

Schema coverage is 100%, and the schema already describes all four parameters in detail. The description adds extra semantic value by clarifying the default for 'models' ('Default model is Workers AI Llama-3.3-70b'), the cost implication of 'anthropic', and that _apiKey is only needed when 'anthropic' is included. This goes slightly 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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from siblings like entity_profile or scan_competitor_ai_presence by focusing on LLM probing with a numeric visibility score. It also states the default model and return format, leaving no ambiguity about 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 provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to pass _apiKey (to also probe Anthropic) and that the default is free Workers AI. However, it does not explicitly name sibling alternatives or state when not to use this tool, 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.

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

Annotations already communicate read-only, open-world, idempotent, non-destructive behavior. The description adds meaningful behavioral context on top: it routes questions to internal tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It could mention rate limits, latency, or subscription requirements, but this is not a major gap given 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 information-rich and front-loaded with the key instruction, but it is longer than necessary and contains repetition, notably the phrase 'START HERE for most questions' appearing more than once. The examples and alternative routing guidance are useful, but the text would benefit from tighter editing.

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

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

For a tool with no output schema, the description does a good job explaining what the agent should expect: a structured answer with stable citation URIs. It also provides trigger phrases, domain coverage, examples, and sibling-tool routing. It does not detail exact output fields or failure modes, but the provided context is sufficient for correct invocation and result handling.

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

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

Schema description coverage is 100%, so the schema fully documents the six parameters and their aliases. The description adds example question forms and natural-language usage patterns, but does not need to re-explain parameter semantics. Baseline 3 is appropriate because the schema does the heavy lifting.

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 defines the tool as a routing/answering layer that prefers structured data over web search, lists concrete domains, trigger phrases, and example questions, and explicitly distinguishes it from siblings like ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research. It tells the agent exactly what the tool does and when to choose it.

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?

Usage guidance is explicit and actionable: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions' are direct instructions. It also names alternative tools and the conditions that select them: grounding → ask_pipeworx_grounded, single answer without links → ask_pipeworx_beta, broad multi-tool questions → deep_research.

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 well beyond the annotations by disclosing the experimental status, the fact that no candidate is currently active, that it currently matches ask_pipeworx exactly, and that it is a full working router with no fallback. This meaningfully addresses the risk that an agent might assume 'beta' means incomplete or unsafe. Annotations are consistent.

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

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

The description is tight and front-loaded: it states the beta relationship first, then current status, usage, and a final clarification. Specific details like 5,798 tools and the retirement date are useful context 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?

For a variant of a known sibling tool, the description covers operational state, usage, relationship to the stable router, and what the tool is not. It does not spell out the response shape, but it references ask_pipeworx's identical response shape, and the sibling tool is available for additional context.

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

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

Schema description coverage is 100%, so the parameter names and alias relationships are already documented. The description adds only the generic cross-reference that ask_pipeworx arguments are the same, without detailing them. This is adequate but adds little beyond the schema.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router over 5,798 tools, and distinguishes it from the stable sibling by emphasizing the experimental candidate routing. It does rely partly on prior knowledge of what ask_pipeworx itself does, which prevents a perfect score.

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 says to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router for merge decisions. It does not spell out 'when not to use' or mention the grounded alternative, but the usage context is still clear.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial value beyond this: the full dual-mode return contract (success shape with evidence/confidence/fetched_at vs. refusal with the complete refusal_reason enum), the open-world routing behavior (5,798 tools across 1517 sources), and the cost implication of an extra LLM call. No contradiction with annotations — openWorldHint aligns with the cross-source routing.

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?

Every sentence earns its place: purpose, mechanism, success return shape, refusal return shape, when-to-use, and cost tradeoff. The most important discriminator ('Hallucination-resistant... high-stakes') is front-loaded as the very first words. Though dense, the length is justified by the complex dual-mode behavioral contract.

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

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

There is no output schema, so the description must carry the full burden of explaining return values — and it does, enumerating both the success object ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and every refusal_reason enum value. Combined with the simple single-parameter schema and rich annotations, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The schema already documents the 'question' parameter and its five aliases (query, q, prompt, text, input). The description adds behavioral context about what happens to the question (routing and grounding) rather than parameter-level semantics, which is fine since the schema carries that burden fully.

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 lead phrase 'Hallucination-resistant answer mode for high-stakes reads' states a specific verb, resource, and behavioral mode instantly. It then differentiates from its sibling ask_pipeworx by explaining the grounded extraction mechanism ('EXTRACTS the answer using ONLY what the tool result contains'), so an agent can tell them apart without opening either schema.

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

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

Gives explicit when-to-use guidance ('Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains (financial verdicts, legal claims, medical lookups, public statements), and explicit when-not-to ('prefer ask_pipeworx for casual lookups') with the cost rationale (one extra LLM call). This is exactly the routing decision information an agent needs.

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 well-covered. The description adds valuable behavioral context by stating the result order matches input order and the maximum batch size of 100, which is not solely derivable from 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 appropriately concise with three short, front-loaded sentences. Each sentence contributes uniquely: the core action, the output behavior/order, and the intended use case. No unnecessary words.

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

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

Given a single-parameter tool with full schema coverage, an output schema, and clear annotations, the description covers all necessary aspects: purpose, batch limit, output contents, ordering guarantee, and usage context. The tool is simple enough that nothing essential is 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 schema provides a complete description of the 'ips' parameter ('Array of IPv4 or IPv6 addresses to look up (maximum 100)'). The description repeats the limit but adds no extra parameter-specific semantics, so it does not go beyond the schema's 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 a specific verb ('look up locations') and resource ('IP addresses'), with clear scope ('up to 100 at once'). It distinguishes itself from sibling geolocate_ip by emphasizing batch processing and return of geolocation and ISP data.

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

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

The description explicitly states 'Use for analyzing multiple IPs efficiently,' which clearly implies batch usage. It does not explicitly mention the alternative single-IP tool geolocate_ip, but the sibling context and batch emphasis make the appropriate use case 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 mark it read-only and idempotent. The description goes far beyond by disclosing fan-out behavior, low-confidence short-circuiting, market_closed_or_inactive handling, wide-spread illiquidity warnings, news fallback mechanics, and resolution-rule risk (e.g., refund_50_50). This is rich behavioral context that annotations alone cannot provide.

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

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

The description is long but densely structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY). It front-loads purpose and input requirements, and each section adds practical detail. Some examples could be condensed, but overall the length is 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?

Without an output schema, the description carries the full burden of explaining return values and edge cases. It covers response shapes (market, analysis, evidence), resolver contract fields, parent-event extraction, news fallback fields, safety short-circuits, and resolution-rule risk. This is exceptionally complete for a tool with this many behaviors.

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

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

Schema covers 100% of parameters with detailed descriptions (market format, depth enum, include_raw defaults). The description reinforces market input options and adds some nuance about include_raw's effect on response size, but it does not substantially extend schema semantics. 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists concrete input forms (slug, URL, question text) and typical use cases ('should I bet on X'), distinguishing this tool from siblings like ask_pipeworx or polymarket_edges.

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

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

Explicit 'Use for' guidance with three query patterns and accepted input formats is provided. The description also warns to inspect resolver contract fields before trusting analysis. It does not name alternatives or state when not to use it, but the context is clear enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, but the description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorting by primary metric, and citation URI returns. This goes well beyond the annotations and gives the agent a clear picture of what will happen.

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 but densely informative. Each sentence serves a purpose: trigger phrases, preference guidance, type-specific data, sorting behavior, and output format. It is well-structured and front-loaded with the core function.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations), the description covers all essential aspects: what it does, when to use, what data it retrieves, how results are ordered, and what the return includes. The absence of an output schema is compensated by describing the return format clearly.

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 both parameters, and the description further enriches semantics with concrete examples and behavior: type='company' pulls financials, type='drug' pulls FAERS counts, values are tickers/CIKs or drug names. It also clarifies the 2–5 range and how results are used.

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: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes from sibling tools like entity_profile (single entity) and search tools by emphasizing the comparative, multi-entity nature and the efficiency advantage.

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: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists trigger phrases and explains type-specific contexts, making it easy to decide when to invoke this tool.

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

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

The annotations already declare read-only and non-destructive behavior, and the description adds strong context: account requirements, structured-source scope, decomposition and parallel routing, the findings-packet shape, explicit gaps[], and the claim that findings are never invented. No contradiction with 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 supplied description repeats the entire opening block verbatim after 'For a single lookup use ask_pipeworx instead', so a large portion adds no new information. The content is logically front-loaded, but the duplication and the long single block hurt readability.

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

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

For a two-parameter tool with no output schema, the description covers prerequisites, scope, decomposition behavior, output packet fields, gap handling, citations, and sibling routing. The schema and annotations cover the remaining parameter and safety details, so nothing critical is missing.

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

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

Schema coverage is 100% and the schema already documents the depth enum and question parameter in detail, so the baseline is 3. The description adds example questions and notes that thorough is paid, but most parametric meaning is already carried by 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?

States a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in ONE call, explicitly distinguishing itself from open-web search. The description also separates it from ask_pipeworx by noting that single lookups should go to ask_pipeworx instead.

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

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

Gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, with concrete examples. It names the alternative tool and the conditions to switch: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond this: returns top-N relevant tools, includes full schemas with examples, and results are directly invokable without further lookup. This fully aligns with annotations and gives the agent confidence in safety and expectations.

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

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

Four sentences, each with clear purpose: purpose, usage, return value detail, and strategic placement. The long list of domains is justified because it helps the agent quickly gauge coverage without excessive verbosity.

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

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

Despite no output schema, the description explicitly states what is returned (tool names, descriptions, full schemas, curated examples), how results are ranked, and when to invoke it. This is complete for the tool's simple discovery purpose.

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

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

Schema coverage is 100% with clear parameter descriptions ('query' accepts natural language, 'limit' defaults to 20 max 50). The description enriches this by explaining that results are ordered by relevance ('top-N'), which the schema alone does not convey. No missing information.

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 ('Find tools') and a clear resource (the tool catalog), then specifies what the tool returns (names, descriptions, schemas). It clearly distinguishes itself from siblings by being the only discovery/browsing tool, explicitly 'Call this FIRST'.

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

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

It states exactly when to use it ('Use when you need to browse, search, look up, or discover what tools exist') and gives strategic guidance ('Call this FIRST when you have many tools available'). It does not mention alternatives, but for a discovery tool that's acceptable since no sibling duplicates this function.

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/non-destructive, and the description adds substantial behavioral detail: parallel fan-out across sources, soft-failure of the sunset USPTO patents API, 'resolved:false' for private companies, empty sections as real absence of data, and sources_used/sources_failed semantics. This goes well beyond the structured 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 the tool is complex and nearly every sentence carries operational information: input forms, output sections, failure semantics, and expected empty results. It is front-loaded with purpose and usage, though some return-field enumeration could arguably be compressed.

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

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

With no output schema, the description carries the full burden of explaining return values and edge cases. It lists the returned sections, explains source-specific behavior (e.g., FDA products absence is expected), specifies URI formats, and clarifies ambiguity around private companies and failed sources. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: accepted input forms (ticker, zero-padded CIK, company name), that names resolve via SEC EDGAR, and that `type` accepts 'company' or 'ticker' interchangeably with identical behavior. These details are not inferable from the schema's enum and property descriptions alone.

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

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

Description opens with concrete natural-language triggers and immediately states the resource: 'full cross-source profile of a US public company in ONE parallel call.' It also distinguishes itself from 'chaining single-pack SEC/XBRL/news lookups,' so the agent can tell this tool apart from siblings without inspecting schemas.

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 prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It identifies the alternative pattern, though it does not explicitly name sibling tools or give a when-not-to-use scenario.

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 annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, covering the key safety behaviors. The description adds little beyond restating the deletion action; it mentions 'previously stored' and 'clear sensitive data' but these are preconditions and use-case rationales rather than new behavioral traits.

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-loads the action, and every clause serves a purpose. It is efficient without unnecessary detail.

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

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

For a single-parameter tool with rich annotations and no output schema, the description fully covers action, usage conditions, and tool relationships. It is contextually complete 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?

The schema fully describes the 'key' parameter with 'Memory key to delete' and includes an example. The description adds no new parameter semantics, and with 100% schema coverage, this is sufficient.

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 'Delete' and the resource 'memory' with scope 'by key'. It distinguishes from siblings by referencing remember and recall, making its role in the memory trio explicit.

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

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

The description explicitly provides usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, indicating related 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 readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context by revealing the fetch behavior, extraction steps, and output format (single text blob in standard markdown). No contradictions with annotations, and it complements them with internal behavior without over-explaining safety.

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: first sentence states core purpose and output, second explains the process, third gives use cases. Every sentence adds value, with no fluff or repetition of schema field labels. It is appropriately sized for a simple two-parameter 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?

For a tool with two parameters, high schema coverage, no output schema, and network-fetch behavior, the description covers the key aspects: what it returns, how it works, and when to use it. It could mention error handling or prerequisites (e.g., network access), but the use cases and output description make it sufficiently complete.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description reinforces the meaning of 'url' by saying 'any URL' and implies max_links through 'key links', but adds no new parameter-specific detail. Baseline 3 is appropriate.

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

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

The description clearly states the specific verb 'Generate' and resource 'llms.txt file for any URL', and details the process (fetch, extract, emit markdown). It differentiates from siblings by focusing on producing the file itself rather than auditing or visibility checks, despite the overlapping competitor use case.

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

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

The 'Useful for' list explicitly provides three concrete scenarios (client sites, own project, competitor audit), giving clear context on when to use the tool. It does not name alternative sibling tools or state when not to use it, which prevents a perfect score.

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 description does not need to repeat safety traits. It adds the specific return fields (country, region, city, coordinates, timezone, ISP, AS number), which is useful context beyond the raw schema. However, it does not disclose any additional behavioral aspects like rate limits or error handling, but given the annotations, the description meets the baseline without contradiction.

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

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

The description is three sentences long, front-loaded with the primary action, and every sentence adds value: the first states the core function, the second lists expected output fields, and the third gives usage context. There is no fluff 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?

For a simple tool with one parameter, rich annotations (readOnly, idempotent, openWorld), and an output schema, the description covers purpose, usage, and return values sufficiently. It lacks explicit differentiation from batch_geolocate, but that is a minor gap. The description is nearly complete for the tool's simplicity.

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

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

Schema description coverage is 100% for the single 'ip' parameter, which is fully described as an IPv4 or IPv6 address. The description's mention of 'IP address' adds no extra semantic meaning beyond the schema. Since the schema already does the heavy lifting, 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 looks up an IP address to find location and network details, with a specific verb and resource. It lists concrete return fields (country, region, city, etc.), making the purpose unambiguous. However, it does not explicitly distinguish this tool from the sibling batch_geolocate, which likely performs a similar operation for multiple IPs.

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 includes a clear usage directive: 'Use when you need to identify where a user or server is located.' This provides context but does not mention exclusions or alternatives, such as batch_geolocate for multiple IPs. It is clear but lacks explicit when-not 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, destructiveHint=false, and idempotentHint=true, so the description doesn't need to cover safety. It adds value by disclosing the return fields (id, type, params, created_at, last_fired_at, fire_count) and the default scope of 'active' subscriptions, which is useful 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 two sentences, front-loaded with the main action and return fields, followed by concise usage guidance. Every word earns its place, with no redundancy or fluff.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It provides the return format, scope (caller's active subscriptions), and usage scenarios. The annotations cover safety, and the schema covers the parameter, 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 already documents the only parameter, include_inactive, with a clear description and default. The description's use of 'active' adds some context about default behavior, but it aligns with the schema's default false. No additional meaning is provided beyond the schema, so the 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 the action ('List the caller's active subscriptions') with a specific verb and resource. It also lists the return fields, which distinguishes it from sibling tools like subscribe and unsubscribe. The use cases ('review what you're monitoring before adding more or to find an id to cancel') further differentiate it.

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 scenarios for when to use the tool: to review active subscriptions before adding more, and to find an id to cancel. This gives clear usage context. However, it doesn't explicitly mention alternatives like subscribe/unsubscribe or state when not to use it, though the context is implied.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for later status checks, that the team reads digests daily, and that it's free. It also warns against pasting end-user prompts, adding practical behavioral context.

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

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

Every sentence earns its place. The description is front-loaded with purpose, lists use cases, gives exclusions, explains token behavior, and ends with rate limits and cost. Though long, it is tightly structured with no redundancy.

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

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

For a feedback tool with nested context objects and no output schema, the description covers all necessary behavior: how to describe issues, token-based follow-up, rate limits, and cost. It also aligns with the sibling-tool landscape by clearly separating from ask_pipeworx and other servers' feedback mechanisms.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and showing claim_token usage syntax ('pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema, justifying a 4.

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

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

The description clearly defines the tool's purpose: to send feedback to the Pipeworx team about broken, missing, or needed functionality. It distinguishes from siblings by explicitly limiting scope to Pipeworx connection tools and categorizing feedback types (bug, feature, data_gap, praise).

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

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

Provides explicit when-to-use guidance: 'Use when 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 gives a clear exclusion: 'if the tool came from a different MCP server . . . 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds key behavioral context: source is CF analytics-engine, no PII, returns only (pack, tool, count), and caching behavior (5min-1h). This fully discloses side effects and data handling.

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

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

The description is well-structured and front-loaded with the core purpose, followed by bulleted use cases and a concise data-source/caching note. Every sentence adds value without redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully explains return content (top tools, packs, call volume, (pack, tool, count)) and includes caching/staleness info. Complete for the tool's complexity.

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

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

The schema already fully describes the 'window' parameter with enum values and guidance on short vs long windows. The description only repeats the enum values without adding new semantic meaning, so the baseline 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb ('returns') and resource. It uniquely describes a trending/aggregation function distinct from sibling tools like discover_tools.

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

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

Provides three explicit 'Useful for' scenarios (discovering hot data sources, confirming canonical tool choice, aligning with agent needs) and gives window-selection guidance ('Shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description goes far beyond that, explaining internal thresholds (>3pp), placeholder filtering (20% limit), Jaccard similarity anchor (≥0.30), and the fill-check behavior with realizable_edge_pp ≤ 0 meaning 'do not trade'. 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 lengthy but packed with crucial details. It is not wasteful; however, it could benefit from clearer section breaks or bullets to improve skimmability. The front-loading of the purpose and usage modes is excellent.

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 explicitly enumerates the response structure (opportunities[], partition_check fields, fill_check fields) and explains edge cases (when signals are not tradeable). It also ties in the related fill-risk tool, making it complete for an agent to decide when and how to invoke.

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 solid schema descriptions, but the tool description adds substantial extra context: examples of slugs and topics, behavioral consequences of each mode, and the semantic anchor logic for topic mode. This enriches the parameter semantics well 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by naming the exact method and scope.

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

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

Explicitly describes the three usage modes: no args for trending_scan, event for single-event partition check, and topic for cross-event scan. It recommends 'event' for specific markets, 'topic' for broader scans, and even points to a sibling tool (polymarket_fill_risk) for custom sizing. This is textbook 'when to use vs alternatives' 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 goes far beyond the annotations by detailing internal model families, filtering logic (e.g., placeholder-slug filters, partition skipping), diagnostics with funnel counters, and the 1-hour KV-level caching keyed on all knobs. It even explains the per-sport alpha values and the rare-by-design nature of concentrated longshots, making the tool's behavior highly predictable.

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 clear segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and a logical flow from purpose to response format to usage knobs. It is front-loaded with the main purpose in the first two sentences, and despite its density, every sentence conveys relevant behavior 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?

With no output schema provided, the description compensates fully by specifying the exact response structure (by_segment, fed_candidates, _diagnostics), the fields carried by each opportunity (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume), and reasons why segments might be empty. It also covers caching behavior and the model families, making the tool's behavior completely transparent.

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 extensive parameter descriptions with 100% coverage, including specifics about min_kelly, min_partition_leg_kelly, and slippage_pp. The tool description only summarizes these knobs (e.g., 'TRADEABLE-EDGE KNOBS'), adding no new parameter-level detail beyond what the schema already contains.

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 clear, specific purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also explains the intended use case ('what should I bet on today'), which distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames when to use the tool ('Built for what should I bet on today') and provides guidance on knobs like min_liquidity and max_spread_pp to drop non-tradeable edges. It also warns that Fed bets are unreliable at certain horizons, helping agents decide when not to rely on those signals.

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 discloses several behavioral traits: snapshots are written only on cache-miss, history depth is bounded by a 60-day TTL, and decay uses daily closes net of default slippage. It also explains the signed edge_pp_net convention and what gaps in snapshot_dates mean.

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 highly structured into Args, RESPONSE, and LIMITS sections, with each sentence carrying meaningful information. It is front-loaded with the purpose and uses formatting to separate concerns, though it is denser 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?

For a tool with no output schema, the description fully specifies the response structure (tracked[], expired[], snapshot_dates[]), their fields and interpretations, as well as data limitations. This gives an agent everything needed to invoke and interpret 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?

The input schema already documents both parameters with defaults and clamps (100% coverage). The description repeats this information with slightly less precision (omits lower clamp for days) and adds no new semantics beyond what the schema provides.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots', which clearly identifies the tool's specific function. It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes it from sibling tools like polymarket_edges by focusing on historical tracking.

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 strong context about when this tool is relevant: it contrasts fresh vs. old edges and highlights the competitive insight from expired[] lifespans. The LIMITS section implicitly defines boundaries (not intraday, 60-day TTL) but no explicit alternative tool is named.

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 non-destructive. The description adds rich behavioral context: walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, and for basket mode per-leg detail, thin_legs, forced_directional_risk. Also warns about partial basket fills and strand risk, going well beyond the annotation safety profile. No contradictions.

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

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

The description is long but information-dense. It front-loads the core purpose, then segregates single-market and basket modes, using uppercase keywords for required parameters and mode names. Each clause adds value, though it could benefit from bullet formatting for readability. It earns its length given the tool's complexity.

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

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

With 4 parameters, no output schema, and no nested objects, the description fully covers what the tool returns in both modes, including edge cases like thin_legs and forced_directional_risk. It also explains the practical arb-bot context (loss mode from partial fills). This is a complete description for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant meaning: market vs event modes, side defaults vary by mode, size_usd interpreted as spend/target proceeds for single-market and settlement notional for basket, including clamp range. This clarifies parameters beyond their 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 opens with a specific verb+object: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges and explaining the fill-risk scenario. It details both single-market and basket modes, making the purpose unambiguous.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500...' It explains why (theoretical overround not capturable, partial fills convert arb into directional risk), giving clear context for choosing this tool over alternatives.

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

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

Annotations already flag readOnly/openWorld/idempotent/non-destructive, and the description adds substantial context beyond them: fees are gross because Kalshi's fee schedule is not modeled, pairings are unverified keyword matches, and temporal_alignment: null means 'could not compute,' not 'aligned.' It also discloses that unknown metric_type/subtype legs are never paired and are routed to skipped/low-confidence structures. No statement contradicts 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 deliberately structured with labeled blocks (TWO MODES, RESPONSE, SAFETY FIELDS) and dense caveats, with the highest-value information front-loaded. Repeated 'BOTH modes/EITHER mode' phrasing could be tightened, but no sentence is filler.

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

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

Despite the absence of an output schema, the description documents the response shape, safety fields, each compatibility code, per-entry flags, skipped counters, and the fee caveat. It even explains the semantics of null temporal_alignment. For a cross-venue comparison with these pitfalls, nothing an agent needs to interpret results is missing.

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

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

Schema coverage is 100% and the schema already describes each parameter with examples. The description adds value by explaining the two calling modes, that explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matcher — turning three flat params into a clear mode relationship. This goes beyond the baseline though it does not add deep per-parameter syntax.

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?

States the exact function up front: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from Polymarket-only siblings by emphasizing the cross-venue comparison, and the two-mode explanation reinforces a specific, non-tautological purpose.

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 mode selection: use a topic shortcut for pre-mapped macros, or supply kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns when results are not trustworthy ('pre-mapped ≠ tradeable', 'real cross-venue spreads are rarer than the macro-shortcut list suggests') and tells the agent to read compatibility fields even when pairs are returned.

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, covering the safety profile. The description adds valuable context by explaining the tool is 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and that omitting the key lists all saved keys, which goes beyond the schema. 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 three sentences, with the core action in the first sentence, usage context in the second, and scoping/relationships in the third. Every sentence contributes distinct value with no repetition or fluff.

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

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

The tool is simple (one optional parameter, no output schema) and the description covers both modes (retrieve by key, list all), the intended use case, scoping details, and companion tools. This is complete 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% for the single key parameter, and the schema describes it as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by explaining the omit-to-list behavior and clarifying that the key must have been previously saved via remember, adding semantic meaning beyond the schema's field 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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', which is a specific verb+resource combination and explicitly distinguishes from sibling tools like remember (save) and forget (delete). It also provides concrete examples of stored context (ticker, address, research notes), making the purpose unambiguous.

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

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

The description states 'Use to look up context the agent stored earlier ... without re-deriving it from scratch', giving a clear reason to invoke this tool. It also says 'Pair with remember to save, forget to delete,' which explicitly names complementary alternatives and how they fit together, making usage conditions 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?

The description discloses a state-changing side effect: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotations' readOnlyHint: true, which claims the operation is read-only. As a result, the description directly contradicts the provided annotation.

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 purpose, followed by return details/filtering and an alternative access point. Every sentence contributes essential information without redundancy.

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

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

Given the five optional parameters are fully described in the schema and annotations cover safety hints, the description adds the remaining needed context: return payload structure, side-effect behavior of mark_read, and external access for scripts/dashboards. It is complete 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%, but the description adds meaning beyond the schema by explaining the effect of mark_read (future calls return only newer events) and providing a concrete type example ('sec_8k'). This enriches the understanding of the type and mark_read parameters.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource that clearly identifies the tool's function. It also lists return fields (source, citation_uri, payload) and filtering options, which distinguishes it from siblings like list_subscriptions (which manage subscriptions) and recent_changes (which may show changes to other resources).

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

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

The description clearly frames the tool for polling alerts and provides an explicit alternative access method ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'). However, it does not contrast this tool with sibling read tools like recent_changes, so it gives context but no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive intent, but the description adds valuable behavioral context beyond them: fan-out to SEC EDGAR, GDELT/GNews fallback mechanism, USPTO soft-fail due to PatentsView API sunset, and the return structure (changes[], total_changes, citation URIs). This helps the agent anticipate real-world behavior like rate-limit fallbacks.

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 appropriately sized given the multi-source tool's complexity. It is front-loaded with user-centric query examples, followed by source details, parameter syntax, and the alternative tool. Some may find it a wall of text, but every sentence contributes necessary information, so it 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?

Given there is no output schema, the description compensates well by describing return values (structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs). It also covers fan-out sources, fallback behavior, and the differentiation from entity_profile. It doesn't detail the exact fields inside changes[], but this is acceptable for a feed tool with no 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 description coverage is 100%, so the baseline is 3. The description adds extra semantic value by elaborating the `since` parameter with supported formats (ISO date or relative shorthand like '7d', '30d') and recommending '30d' or '1m' for typical monitoring. It also reiterates `value` as ticker or CIK, but the main additive value is for `since`.

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 defines the tool as a 'change feed for a company in the last N days/weeks/months' with concrete query examples like 'What's new with X' and 'news on Tesla recently'. It explicitly distinguishes itself from entity_profile by directing users seeking static profiles to that sibling tool, satisfying the sibling-differentiation criterion.

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 via query patterns and the 'ONE parallel call' efficiency note. It also gives a clear when-not-to-use instruction: 'Use entity_profile instead when you want the static profile... regardless of window.' This is a direct alternative recommendation.

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 write behavior (readOnlyHint false), idempotency, and non-destructiveness. The description adds valuable context beyond annotations: memory is scoped by the agent's identifier, with different persistence for authenticated vs anonymous sessions. This enriches the agent's understanding of side effects.

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

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

The description is four sentences: first states the core purpose, second gives usage context, third explains storage/scoping, and fourth names companion tools. Every sentence earns its place with 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?

For a simple two-parameter tool, the description covers the core action, usage timing, persistence behavior, and related tools. Annotations cover safety and idempotency; schema covers parameters. No output schema is necessary for a save operation, so the description is sufficiently complete.

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

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

The input schema already provides 100% coverage with clear descriptions for both key and value, including examples. The description reinforces the key-value nature and adds the scoping detail, but doesn't offer additional syntactic or format guidance. Baseline 3 applies since the schema carries the burden.

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 data') and clearly identifies the resource: reusable information stored as a key-value pair. It also distinguishes itself from sibling tools by explicitly pairing with recall and forget, and the title/name are consistent.

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

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

The description explicitly states when to use the tool ('Use when you discover something worth carrying forward') and gives concrete examples (resolved ticker, target address, user preference). It also names the companion tools for retrieval (recall) and deletion (forget), providing clear alternatives.

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

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

Annotations already mark the tool read-only, idempotent, open-world, and non-destructive. The description goes well beyond that by disclosing internal multi-endpoint cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, source-labelled identifiers, and `figi_candidates` for ambiguous matches. 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 contains almost no waste and front-loads examples and the key 'Use FIRST' routing instruction. However, the main body is one very dense paragraph with deeply nested parentheticals, which makes it harder to scan than an ideal structured description with clear separation per entity type.

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

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

For a complex two-parameter tool with no output schema, the description is remarkably complete: it covers both entity branches, identifier families returned, source labelling, unresolved identifiers, ambiguous security matches, and degraded enrichment behavior. An agent has enough information to 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%, but the description adds substantial meaning beyond the schema: it explains that `value` accepts ticker, CIK, ISIN, or company name; distinguishes drug brand vs generic input; and warns not to append security-class words when resolving bond issuers. This materially improves correct invocation.

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 ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), with trigger-phrase examples that show exactly what category of question it answers. It also names supported entity types and frames itself as the tool that supplies IDs other tools require, which separates it from profile/compare siblings.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and gives example phrasings plus acceptable input forms, which is clear usage guidance. It does not name alternative tools or state when not to use it, so it lacks a full when/when-not exclusion set.

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. The description adds valuable behavioral details: it probes each entity with ai_visibility_check, ranks by score, treats the first entity as the 'subject' for narrative, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations without contradicting them, though it doesn't mention rate limits or potential failures.

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

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

The description is concise and front-loaded with the primary purpose. Four sentences deliver the action, the mechanism, a use case, and the return format without waste. Every sentence earns its place.

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

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

For a read-only comparison tool with full schema coverage and detailed annotations, the description provides all necessary context: what it does, how it works, when to use it, and what it returns. The absence of an output schema is compensated by the explicit statement of return fields. It is complete for an agent to select and invoke correctly.

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

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

The input schema already has 100% description coverage for all parameters, so the baseline is 3. The description adds extra meaning by explaining that the first entity in the 'entities' array is treated as the subject for narrative, which is not in the schema. This lifts the score to 4.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare'), identifies the resource ('AI visibility'), and distinguishes itself from the sibling tool ai_visibility_check by focusing on multi-entity comparison. It also provides a concrete use case example, making its purpose unmistakable.

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

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

The description gives clear context for when to use the tool: 'Useful for competitive AI-marketing audits' with an example question. It does not explicitly name alternatives or exclusions, but the multi-entity focus implicitly differentiates it from single-entity tools. The guidance is strong but could benefit from an explicit 'use this instead of ai_visibility_check for multiple entities.'

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

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

While annotations already declare readOnlyHint and idempotentHint, the description adds substantial behavioral context: it fans out across two external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeout cases. This goes beyond basic safety hints to describe latency and failure behavior, which is valuable 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 longer than ideal but every sentence carries information: purpose, fan-out architecture, usage trigger, output summary fields, ecosystem limitation, and performance caveat. It is front-loaded with the core purpose and then logically organized. A slight deduction for density, but no wasted words.

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

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

Given the tool's complexity (multi-source, composite check) and the absence of an output schema, the description is remarkably complete. It lists the exact return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), covers failure modes, and explains ecosystem constraints. An agent would know exactly what to expect and when 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters beyond what the schema already provides (package name and optional version). However, it does contextualize the parameters by mentioning the NPM ecosystem and the default to latest version implicitly, but not in a way that adds new semantic detail.

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, action-oriented statement: a composite 'should I add this npm package to my project' check. It clearly identifies the tool's scope (scanning dependencies) and differentiates it from siblings by naming the specific data sources (deps.dev and bundlephobia) and the question it answers (safe/popular/small).

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

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

Explicitly says when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', steering users toward alternatives. This is clear when/when-not 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?

Beyond the annotations (readOnlyHint, etc.), the description discloses significant behavioral details: embedding model (BGE-base-en), similarity method (cosine), windowing strategy (500-char overlapping windows), hard cap (200K chars), and truncation flagging. It also tells the agent what each passage contains (character offsets and similarity scores). 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 substantial but every sentence earns its place. It opens with the core purpose, then usage context, then specific technical parameters. The structure is front-loaded and clear, with no filler or repetition of schema fields. Appropriate length for 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?

Given the tool has 3 parameters, no output schema, and moderate complexity, the description fully equips an agent to use it correctly. It covers input requirements, output shape (passages with offsets/scores), usage triggers, limitations (200K cap, truncation), and relationships to sibling tools. Nothing essential is missing.

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

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

Schema coverage is 100% (all 3 parameters documented in the schema), so baseline is 3. The description adds value by clarifying the intent for 'text' (fetched record), giving example queries for 'query', and mentioning the truncation behavior tied to 'text'. This goes beyond the schema's basic descriptions, warranting a 4.

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

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

The description clearly states a specific verb and resource: 'Semantic search INSIDE a fetched record.' It distinguishes itself from sibling tools by emphasizing the 'inside a fetched record' use case and explicitly naming ask_pipeworx_grounded as a companion. The purpose is unmistakable.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only relevant passages). It also names a sibling alternative (ask_pipeworx_grounded) and describes the pairing workflow, giving clear context and exclusions.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), it discloses OAuth account requirement, SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 failures. This is rich behavioral context.

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

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

Three structured sentences front-load the purpose and then pack type-specific and delivery-specific details without redundancy. Every clause adds useful operational information.

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

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

Covers auth, delivery channels, limits, webhook behavior, and return value. It is not fully complete because it omits two schema enum types in the description, though the schema covers them and output schema is absent.

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

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

Schema coverage is 100%, so baseline is 3; the description adds concrete examples for sec_8k, polymarket_edge, and fred_series params and delivery channel syntax. However, it lists only three of the five enum types and omits patent_grant and clinical_trial, making its 'Supported types' list incomplete.

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 opening verb 'Create' and resource 'proactive monitoring subscription' clearly define the operation. It also states the return value ('Returns the new subscription id'), distinguishing it from siblings like list_subscriptions and recent_alerts.

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

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

The description specifies prerequisites (Pipeworx OAuth account, anonymous/BYO cannot persist) and supported subscription types. It points to recent_alerts/GET URL for consuming the always-on feed, but does not explicitly contrast with list_subscriptions/unsubscribe or state when not to subscribe.

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, non-destructive, open-world, idempotent. The description supplements with concrete behavioral specifics: returns category-bucketed example questions, each paired with the exact tool and argument shape, drawn from the live catalog. This explains the internal response structure and adds substantial context beyond the annotation hints.

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, long sentence with multiple examples and clauses, but it remains well-organized and front-loaded with user queries. It packs a lot of useful information without unnecessary repetition, though it could be tighter by splitting into shorter sentences.

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 explains what the tool returns (category-bucketed example questions with tool+argument shape) and how to focus results via the topic parameter. Given the low complexity (one optional parameter) and complete annotations, there are no significant informational gaps 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 coverage is 100% and the schema already describes the optional 'topic' parameter with allowed values and the omit-for-full-spread behavior. The description restates this in prose but adds minimal new semantic detail beyond giving examples of topic values (finance, pharma, betting) that are already in the schema's enum-like description. Baseline 3 applies.

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

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

The description opens with specific natural-language queries ('What can I ask Pipeworx?') and clearly states its role as the onboarding entry point for new agents. It defines the resource (example questions with tool+argument shape) and distinguishes it from broader discovery tools by emphasizing its focus on generating actionable suggestions.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and extends the guidance to learning how to call meta-tools. This provides a clear when-to-use context, effectively positioning it relative to the agent's initial state.

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

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

The description adds meaningful behavioral context beyond the annotations: ownership enforcement is an authorization requirement, and 'deactivated (not deleted)' explains the non-destructive nature. While the annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description supplements with specifics about deactivation and ownership, 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 two sentences, front-loaded with the core action, and every sentence adds information. There is no redundancy or fluff.

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

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

For a single-parameter mutation tool with strong annotations, the description covers purpose, authorization, and the impact on historical data via recent_alerts. The reference to recent_alerts connects to a sibling tool for context. No output schema is provided, so return values are not a gap. The description is complete for its complexity.

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

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

The input schema fully describes the only parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'). The description's phrase 'by id' adds no further semantic detail. Schema coverage is 100%, so the 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 the action ('Cancel a subscription by id') and the resource (subscriptions). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying cancellation, and the ownership rule adds a specific constraint.

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

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

The description provides a clear context for use: canceling your own subscriptions only. It also mentions a consequence (historical events remain via recent_alerts) which implies an alternative for accessing history. However, it does not explicitly state when not to use the tool or name alternative tools for managing subscriptions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: exact verdict vocabulary, evidence with pipeworx:// citations, structured verification_error for could_not_verify, and the explicit warning that could_not_verify is neutral evidence. 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 logically organized: trigger phrases, usage directive, routing rules, return contract, and caller caveat. Every sentence adds value, though length is above average; the structure (with the IMPORTANT note) aids readability.

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

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

Even without an output schema, the description fully covers the return contract (verdict types, actual value, citation, reasoning), error semantics (verification_error), and both execution paths. It gives the agent enough context to invoke correctly and interpret results 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%, and the description supplements it with practical meaning: tolerance_pct default is implied by claim wording and capped at 5, with guidance to set 1–2 for hallucination detection. The claim parameter is illustrated with examples that clarify expected input.

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 explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by describing a specialized two-path routing (SEC EDGAR for company financials, grounded pipeline for anything else) and by noting it replaces 4–6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides concrete routing rules (financial vs non-financial) and clarifies the meaning of special verdict states (could_not_verify vs unsupported), helping the agent decide when to call this tool and how to interpret results.

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