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 declare readOnlyHint, openWorldHint, and idempotentHint. The description adds useful behavioral context: it routes to '5,529 tools across 1455 verified sources', 'fills arguments', and returns 'structured answer with stable pipeworx:// citation URIs.' It also notes 'works on every tier, one fast call.' No contradictions found, though failure modes are not discussed.

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 typical but information-dense, starting with a clear directive and including examples, alternatives, and scope. Every sentence adds value, though it could be tightened slightly. The structure is logical: purpose, usage, alternatives, examples.

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 routing tool with no output schema, the description is remarkably complete. It explains the tool's breadth, return format (structured answer with citation URIs), performance characteristics ('one fast call'), and how it fits among alternatives. It also covers data categories and typical use cases, leaving little ambiguity for the agent.

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

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

Schema coverage is 100% and the question parameter is well-documented with aliases. The description adds examples of valid questions, which helps, but it does not explain parameter syntax or edge cases beyond what the schema provides. 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 states a specific verb+resource: it 'routes the question to the right one of 5,529 tools' and 'returns the structured answer with stable pipeworx:// citation URIs.' This clearly distinguishes it from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicit guidance is front-loaded: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' It lists trigger phrases ('what is', 'look up', 'find', etc.), provides concrete examples, and names alternatives with when to 'step up only when needed.' It also covers breaking-news cases, making usage rules exceptionally 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: it is an experimental beta where candidate routing improvements can be enabled live, currently matches the stable version exactly, and 'falls back to nothing' meaning it is a fully functional router, not a stub. This informs the agent that behavior may change over time and is not just a read-only operation but an active experimental edge.

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

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

The description is front-loaded with the key purpose ('Beta version of ask_pipeworx') and includes necessary details about candidate status, usage, and fallback behavior. While slightly verbose (e.g., specific tool count and date), each sentence contributes meaningful context, making it structured and efficient enough.

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 high schema coverage, annotations, and the explicit reference to 'same response shape' as ask_pipeworx, the description adequately covers purpose, usage, current state, and functional guarantees. It omits explicit return-value details, but the comparison to ask_pipeworx provides sufficient context for an agent familiar with the sibling tool.

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

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

Schema description coverage is 100%, with all six parameters (question and five aliases) described in the schema. The description adds no extra parameter-level meaning beyond confirming 'same arguments' as ask_pipeworx. Baseline of 3 is appropriate since the schema already fully documents parameters.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, specifying it is a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx by emphasizing the experimental routing improvements, making the purpose specific and differentiated.

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

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

It explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also mentions that results are compared against the stable router, implying the stable ask_pipeworx is the alternative for production use. This provides clear when/when-not guidance and names the primary alternative.

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 (readOnlyHint, openWorldHint, idempotentHint) by disclosing the exact return format on success and the explicit refusal behavior with a finite list of refusal reasons. It explains the internal routing and extraction mechanism, the extra LLM call cost, and the condition under which refusal occurs. This provides substantial behavioral context without contradicting any 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 front-loaded with the main purpose and then provides detailed behavioral and usage context. It is a bit dense but every sentence contributes value: the refusal mechanism, use cases, cost trade-off, and sibling comparison are all relevant. It earns its length, though it could be slightly tightened by removing redundant routing details. Overall, it is well-structured and not verbose.

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

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

Given the tool's complexity (routing across thousands of sources, grounded answer mode), the description is complete. It explains the return format (since there is no output schema), success and refusal conditions, the extra cost vs. ask_pipeworx, and appropriate use cases. This is sufficient for an agent to decide when to invoke it and what to expect, making it fully contextual.

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

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

Schema description coverage is 100%, with all six parameters (aliases for 'question') already documented in the schema. The description does not add parameter-specific semantics beyond what the schema provides, but it does reference the internal process of 'fills arguments' and 'fetches the data,' which is not parameter-level detail. Given the high schema coverage, 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 tool's purpose: a 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the core function (answer extraction with grounded evidence) and distinguishes it from the sibling tool ask_pipeworx by emphasizing the grounded/refusal behavior and the extra cost. This is a specific verb+resource+mode that differentiates it clearly.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also explicitly advises against casual use: 'prefer ask_pipeworx for casual lookups.' This clearly states when and when not to use the tool relative to alternatives.

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

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

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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds substantial non-obvious behaviors: time expectations (15-60s, up to ~90s for thorough), explicit gaps[] when data is missing, contradictions[] for deeper levels, the hop field, and the condition that citation_uri is only present when resolvable. It also explains semantic excerpting, which is beyond annotation coverage and highly useful. 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 a single dense paragraph, but every sentence carries operational value—account requirements, alternatives, output format, timing, and exclusions. However, the lack of headings or bullets and the placement of the account note before the core purpose hurt scannability, so it is not maximally concise.

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

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

With no output schema, the description compensates fully by specifying the findings packet fields (verbatim evidence, confidence, source, fetched_at, citation), the gaps[] and contradictions[] arrays, the hop field, and time bounds. It also covers account tiers, depth semantics, and explicit exclusions, making it self-sufficient for a multi-source research tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the question parameter ('Broad/multi-part is fine — decomposition is the point') and giving richer context on depth trade-offs (e.g., standard 're-angles unanswered gaps' while thorough 'chases the best leads'), which supports schema enum descriptions. Much is redundant with the schema, but the added context justifies 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 opens with 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call', providing a specific verb+resource and immediately distinguishing itself from open-web search and sibling tools like ask_pipeworx. Concrete examples of broad questions further clarify its intended use, making the purpose unmistakable.

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

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

Usage guidance is explicit: 'Best for broad/multi-part questions over structured data', with clear alternatives for single lookups ('For a single lookup use ask_pipeworx') and current-events topics ('prefer ask_pipeworx ... deep_research returns mostly empty gaps[]'). It also covers account prerequisites and a fallback for unsigned-in users, plus depth-level recommendations, so the when/when-not is fully addressed.

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?

Beyond annotations (readOnlyHint, openWorldHint), the description reveals rich behavioral details: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF in one parallel call; mentions specific components returned; and discloses the patents API sunset with soft-fail behavior and GDELT→GNews fallback. This gives the agent a clear picture of what happens.

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

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

The description is long but front-loaded with example queries and every clause adds value: what it returns, data sources, fallbacks, and limitations. It could be tightened but remains well-structured and informative for a tool with multiple data-source integrations.

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 and high complexity, the description compensates fully by enumerating the exact return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), including specifics like 'up to 5' filings and 'latest 10-K' data. It also covers edge cases (patents soft-fail, name-not-supported) and references the required zero-padding for CIK.

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

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

The input schema covers 100% of parameter semantics, so baseline is 3. The description adds concrete examples (ticker 'AAPL', zero-padded CIK '0000320193') and reinforces the constraint that names are not accepted, which aids correct invocation and reduces errors.

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 builds a 'full cross-source profile of a US public company' with a specific verb and resource. It includes multiple example queries ('Tell me about X', 'research Acme') and differentiates from sibling tools like resolve_entity and compare_entities by specifying the holistic, one-call nature.

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 to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and provides a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This gives direct when-to-use and alternative guidance.

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

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

The 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?

Even though annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds extensive behavioral detail: compatibility_warning firing conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and token-overlap matcher behavior. This goes far beyond the annotations and helps the agent anticipate edge cases and interpret output.

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 (about 250 words) but well-structured: purpose, modes, response format, safety fields, and caveat. Each section earns its place, and the content is dense with useful details rather than fluff. It could be slightly tightened, but the structure is clear and front-loaded.

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

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

With no output schema, the description thoroughly explains the response structure (leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype). It covers mode selection, safety warnings, and limitations, making the tool understandable and actionable for a complex cross-venue comparison.

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 three parameters have descriptions), but the description adds meaningful semantic context: it defines the two modes (topic vs explicit) and explains that explicit event ticker/slug 'Overrides the topic-mapped' side. This adds value beyond the raw schema fields, though the schema already covers basic descriptions.

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

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

The description immediately states the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This uses a specific verb ('spread') and resource (Kalshi/Polymarket), and clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on cross-venue same-question price differences.

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

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

The description explains two usage modes ('topic' and explicit kalshi_event_ticker + polymarket_event_slug) and provides clear context for when the spread is meaningful ('when the bet shapes are equivalent'). It also warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility_warning, giving realistic expectations. It does not explicitly name alternative tools, but the guidance is otherwise strong.

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

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

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?

The description discloses behavioral details beyond the annotations: LEI/FIGI enrichment degrades gracefully, identifiers are labelled with source, unresolved identifiers are stated under `unresolved` rather than omitted, and each call cascades through several lookup endpoints. This gives the agent insight into edge cases and resilience, complementing the readOnly/idempotent 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 substantial but well-organized: it opens with example queries, then a crisp purpose statement, followed by supported types and graceful degradation notes. However, it contains dense jargon like 'cross-source identity spine' and a 'pipeworx://' citation URL that may be more verbose than needed for an AI agent to select and invoke the tool correctly, slightly reducing conciseness.

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 comprehensively explains what identifiers are returned for company (CIK, ticker, LEI, FIGI, ownership) and drug (RxCUI, ingredient, brand), how unresolved items are surfaced, and the graceful-degradation behavior. This fully equips the agent to understand the tool's outputs and limitations.

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 provides 100% coverage for both parameters (type and value) with detailed descriptions and examples. The tool description does not substantially add parameter-level semantics; it mostly elaborates on output behavior and source details, which are not parameter-specific. Thus 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 resolves user-spoken names to canonical identifiers, exemplified with query patterns like 'What's the ticker for…' and 'look up the ID for…'. It distinguishes itself from siblings by positioning it as the first lookup when a name needs an ID, and it explicitly enumerates supported entity types (company, drug) and identifier sources.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving a clear directive for when to invoke this tool over alternatives. It also explains that it replaces 2-3 manual lookups, and details accepted input formats (ticker, CIK, name; brand/generic drug name), which aids correct usage.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. 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.