wger

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

The description adds valuable context beyond the annotations: the default model (Workers AI Llama-3.3-70b) is free, while probing Anthropic requires a BYO key and direct payment. It also outlines the return structure per model. These details are not implied by the readOnly/openWorld/idempotent hints, so they enhance transparency.

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

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

The description is concise and front-loaded with a clear action verb. Every sentence adds value: purpose, default behavior, cost implications, return format, and use cases. It is information-dense without being 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?

Despite having no output schema, the description explicitly details the per-model return object and the combined view. Combined with coverage of use cases, defaults, and costing, the description provides a complete picture for a tool with only 4 parameters and no complex nested structures.

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% coverage with detailed descriptions for all 4 parameters, including the free default and the `_apiKey` requirement. The description's mention of the default model and BYO key largely repeats the schema, adding little new parameter-level meaning.

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

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

The description clearly states what the tool does: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It is specific with verb and resource, but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence, which might overlap in purpose.

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

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

The description provides concrete use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It clearly implies when to use the tool but does not offer explicit exclusions or alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context: automatic tool routing, argument filling, structured output, and stable pipeworx:// citation URIs, which go beyond what the annotations or schema communicate.

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

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

The description is long but front-loaded with the most important directive and dense with examples and routing guidance. It is somewhat repetitive (e.g., “PREFER OVER WEB SEARCH” and “even if web search could also answer it”), but most sentences earn their place by clarifying scope, triggers, or alternatives.

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 does enough by stating that the result is a structured answer with citation URIs. It covers a wide range of scenarios, provides examples, and routes the agent away from this tool when deep_research is more appropriate. It does not mention failure modes or explicit output schema structure, but for a free-form question tool this is not a critical gap.

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 parameter-level detail, though the examples illustrate acceptable natural-language question formats. This is useful but does not substantially expand on the schema's own explanation of the `question` parameter and its aliases.

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 action: routes the question to one of 5,767 tools across 1,506 verified sources and returns a structured answer with citation URIs. It also gives concrete use categories and examples. However, it does not explicitly distinguish ask_pipeworx from close siblings like ask_pipeworx_grounded or ask_pipeworx_beta, so it is not fully differentiated within its own tool family.

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

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

The description is explicit about when to prefer this tool over web search, lists trigger phrases and examples, and names an alternative (deep_research) for broad/multi-part questions. It also tells the agent to “START HERE for most questions,” leaving no ambiguity about default routing.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral context: candidate routing improvements are enabled live whenever under test, no candidate is currently active (as of 2026-07-26), so behavior currently matches ask_pipeworx exactly. It also discloses that behavior may change with future candidates, which is beyond what annotations provide.

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

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

The description is concise, front-loaded with the essential identity ('Beta version of ask_pipeworx'), and every sentence earns its place: relationship to stable, current status, usage condition, and correction of fallback misconception. No filler or repetition exists.

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

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

The description covers identity, current operational state, usage guidance, and corrects a key misunderstanding. It references the same response shape as ask_pipeworx but does not independently describe the return payload; however, given the tool delegates to the stable router and there is no output schema, this is a minor gap. Overall, the information needed to invoke it correctly is present.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the required 'question'. The description adds only the pointer that arguments are the same as ask_pipeworx, which is minimal extra meaning. Baseline 3 is appropriate because the schema already carries the parameter documentation 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 clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by the experimental candidate routing improvements, so an agent can tell what this tool is and how it differs from ask_pipeworx.

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 clarifies the beta purpose (results compared against the stable router) and corrects a potential misconception by stating it is a full working router, not a fallback. This gives clear selection guidance relative to the stable 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 annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds substantive behavior beyond that: refusal semantics, exact refusal_reason values, verbatim evidence quoting, and the 'ONLY what the tool result contains' grounding constraint. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core behavior, then covers return shapes, use cases, and alternatives in five dense sentences. Every sentence adds a distinct piece of information with no filler.

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

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

Complete despite no output schema: it describes both success and refusal payloads, typical high-stakes domains, the extra LLM call cost, and the correct sibling to use for casual lookups. An agent has everything needed to invoke and interpret the result.

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 has 100% description coverage and documents all six parameters as aliases for the natural-language question. The description adds no parameter-level detail, but it doesn't need to because the schema fully covers semantics.

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

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

The description leads with a specific mode: 'Hallucination-resistant answer mode for high-stakes reads' and clearly explains how the tool works: it routes like ask_pipeworx, fetches data, then extracts an answer only from the tool result. This makes it distinct from the sibling ask_pipeworx and other answer-generation 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?

Explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups'. It names the alternative and explains the cost tradeoff, so an agent can choose correctly without ambiguity.

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, so the safe-read profile is known. The description adds extensive behavioral context beyond these: resolver confidence levels, low-confidence short-circuit behavior, blocking paths for closed/dead markets, illiquid wide-spread handling, news fallback fields, and cancellation-rule risk. This is rich, actionable transparency.

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

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

The description is long but highly structured with clear labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every sentence contributes technical detail essential for correct invocation, but the length is at the upper bound of what is 'appropriately sized'. The front-loaded purpose sentence helps orientation.

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

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

Given the tool's complexity and absence of an output schema, the description meticulously documents all relevant return shapes, resolver behavior, parent-event extraction, news fallback, safety statuses, and cancellation-rule risk. It covers edge cases (closed markets, low-confidence matches, wide spreads) that an agent would otherwise encounter blind.

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

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

Schema description coverage is 100%, with each parameter (market, depth, include_raw) already described in the schema. The description doesn't add new parameter semantics beyond restating input formats (slug/URL/question) and providing examples, which are already in the schema. It meets the baseline but doesn't exceed it.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and distinguishes itself from generic research tools by its market-resolution and fan-out behavior.

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

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

Explicit usage guidance is provided: 'Use for...' gives clear triggers. The fan-out examples illustrate when each classifier/strategy applies, and the resolver contract warns about 'medium/low matches' guiding when to trust results. Though it doesn't name sibling alternatives, it provides sufficient context for when this tool is appropriate.

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

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

Beyond the readOnly and idempotent annotations, the description reveals substantial behavioral details: parallel execution, data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradictions with annotations; it adds rich context about how the tool operates.

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

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

The description is dense but well-structured, starting with query examples then core function, then type-specific details and return behavior. Every sentence adds value, though the paragraph is long. Front-loading the purpose and usage guidance makes it effective, so it earns a 4 rather than 5 only because it could be slightly more compact.

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 explains what the tool returns ('paired data + pipeworx:// citation URIs per entity'), how results are sorted, and the specific metrics for each entity type. It covers all essential aspects for selection and invocation, including examples and edge cases like off-calendar fiscal years, making it highly 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?

Although the schema already covers both parameters at 100%, the description enriches their meaning: 'type' is explained with its enum values and what data each pulls, and 'values' is clarified with examples and constraints (2–5 tickers or names). This goes beyond the schema's basic descriptions, giving the agent a deeper understanding of how to populate them.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It includes concrete query examples and specific data pulled for each type, and distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Provides explicit guidance on when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This directly contrasts with likely alternatives like entity_profile, making it clear this tool is for multi-entity comparisons, not single-entity lookups. The 'Replaces 8–15 sequential lookups' further reinforces its use case.

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/openWorld/idempotent hints, the description discloses account and paid-plan requirements, parallel facet decomposition, the findings-packet return shape, gaps[], contradictions[], citation fetchability, semantic excerpting, and expected latency. It also states explicitly that findings are never invented, adding important grounding behavior not visible in annotations.

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

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

The description is long but dense and well-structured. It opens with the most decision-critical constraints (account, alternative, intended scope), then proceeds into return semantics and performance. Every sentence earns its place; there is no filler or repetition of schema content.

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

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

There is no output schema, but the description compensates fully by describing the findings packet: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], and contradictions[]. Combined with auth requirements, alternative tool recommendations, and latency expectations, an agent has everything needed to decide whether and how to call 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?

The input schema already covers both parameters at 100%, so the baseline is 3. The description adds meaningful selection context beyond the schema: depth:'thorough' requires a paid plan, standard and thorough add contradiction scans, and latency expectations differ by depth. This helps the agent choose a depth value rather than merely parse the enum.

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 and resource: grounded multi-source research in one call over Pipeworx's structured data sources. It explicitly says this is NOT open-web search and gives concrete examples like 'compare X and Y's regulatory + financial exposure', making the tool's scope easy to distinguish from siblings.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'). It also provides an access-based alternative: if the user is not signed in, use ask_pipeworx. This is strong routing information.

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, so the description's safety profile is clear. The description adds valuable behavioral context beyond annotations: it returns top-N relevant tools with names, descriptions, and full input schemas, and notes each result is ready to call directly without a second schema lookup. This sets accurate expectations 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 four sentences with no fluff. It front-loads the purpose, then usage context, then return-value details, then strategic advice ('Call this FIRST'). Every sentence earns its place, making it highly efficient.

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

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

Despite having no output schema, the description explains the return structure (names, descriptions, schemas with curated examples) and the appropriate use case. Given the tool's read-only, discovery nature and the richness of the parameter schema, the description is fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by enumerating example topic areas (e.g., 'SEC filings, financials, revenue, profit, FDA drugs...'), giving the agent concrete sense of what queries to use. This supplemental guidance earns a 4.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this meta-discovery tool from its domain-specific siblings by stating it returns ready-to-call tool schemas and advising to 'Call this FIRST' when exploring options. This makes 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 provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and lists many concrete domains (SEC filings, FDA drugs, etc.). It also recommends calling first when many tools are available. However, it does not explicitly state when not to use it or name specific alternatives, so it falls short of a 5.

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

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

The description goes far beyond the annotations: it discloses soft-fail behavior (USPTO sunset), expected empty sections, the meaning of sources_used/sources_failed, name-resolution behavior, and the resolved:false path for private companies. It also explains why fda_products may be empty, preventing false bug reports. No contradiction with readOnly/idempotent/openWorld 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 long but dense with essential details and front-loaded with example queries and the key 'ONE parallel call' concept. It is structured as one large paragraph with semicolon-separated clauses, which is readable for a complex tool, but line breaks or bullet-like separation for the many return fields would improve scannability.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: it lists every section (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI) and explains failure semantics. It also covers parameter semantics, input resolution, and expected empty-data cases, leaving little ambiguity for an agent invoking or interpreting results.

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

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

Schema coverage is 100% for both params, so the baseline is 3. The description adds meaning by showing the accepted value shapes with concrete examples, emphasizing that type accepts 'company' or 'ticker' interchangeably, and clarifying zero-padded CIK formatting and SEC EDGAR name resolution. This adds genuine value beyond the schema's enum and 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 leads with concrete user queries ('Tell me about X', 'research Acme') and states a precise verb+resource: full cross-source profile of a US public company in one parallel call. It clearly differentiates from siblings like resolve_entity and compare_entities by describing the comprehensive multi-source fan-out and the exact sections returned.

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

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

It explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', giving a clear when-to-use rule. It also explains valid inputs (ticker, CIK, name) and the private-company fallback behavior, so an agent knows when this tool is appropriate and what to expect for non-match cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds usage context but no extra behavioral depth beyond the obvious deletion action. It does not mention what happens if the key doesn't exist or whether deletion is permanent, but the annotations sufficiently signal destructiveness.

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

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

Two concise sentences: the first states the core function, the second provides usage conditions and sibling pairing. Every word earns its place, no redundant content.

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

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

For a single-parameter, no-output-schema deletion tool, this is complete. It covers purpose, usage context, and relationship to sibling tools. The annotations fill in the destructive semantics, so nothing critical is missing.

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

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

Schema coverage is 100%: the only parameter 'key' is described as 'Memory key to delete'. The description's phrase 'by key' adds nothing beyond the schema, so the 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 uses the specific verb 'Delete' with a clear resource ('a previously stored memory by key'), immediately distinguishing it from sibling tools like remember and recall. It also mentions these siblings explicitly, reinforcing its unique role in the memory workflow.

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 the tool ('when context is stale, the task is done, or you want to clear sensitive data') and even advises pairing with remember and recall, giving clear contextual guidance without needing to consult sibling descriptions.

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

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

The description discloses the key behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also explains the output as a 'single text blob ready to drop at site-root/llms.txt.' The annotations (readOnlyHint, idempotentHint, destructiveHint) cover safety, and the description adds process-level detail without contradicting those annotations.

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

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

The description is concise and front-loaded: the first sentence states the primary purpose, the second summarizes the process and output, and the final clause lists use cases. Every sentence adds value 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?

Given the tool's simplicity (2 params, no output schema), the description is sufficiently complete: it explains the input (URL), the process, the output format, and the practical applications. The annotations cover safety and idempotency. No major gaps remain, though it could mention edge cases (e.g., invalid URLs) but that is not critical for this straightforward generator.

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 both 'url' and 'max_links' fully documented in the schema (including default and max values). The description adds little param-specific meaning beyond the schema, though it does explain the practical source of links ('extracts title/description/key links'). This meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Generate a production-ready llms.txt file'), the resource ('for any URL'), and the specific output format ('standard llms.txt markdown'). It also lists concrete use cases (getting a client's site indexed, drafting for own project, auditing a competitor) which distinguishes it from sibling tools like ai_visibility_check and scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to invoke this tool. It does not explicitly state exclusions or name alternative tools, but the guidance is specific enough for an agent to select it 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds no additional behavioral context (e.g., error handling, caching, or existence requirements) beyond confirming it is a read operation. Since annotations carry the burden, a 3 is appropriate.

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

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

The description is a single, concise sentence that front-loads the action and resource. No unnecessary words or repetition.

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

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

The tool has a single parameter, a rich output schema, and clear annotations. The description fully explains the tool's purpose and input requirement. There is no need for additional detail about return values or behavior since the output schema and annotations cover them.

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

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

The input schema has 100% parameter description coverage: 'The numeric wger exercise ID.' The description's phrase 'by its numeric ID' only restates what the schema already explains, adding no new meaning. Baseline 3 is applied.

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: 'Get detailed information for a specific exercise by its numeric ID.' It uses a specific verb ('Get'), identifies the resource ('specific exercise'), and distinguishes itself from sibling tools like list_exercises by focusing on individual items.

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

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

The description implies the appropriate use case (when you have a numeric ID and need details), which is clear context. However, it does not explicitly exclude alternatives like list_exercises or mention when not to use it, so it falls short of a full 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 read-only, idempotent, non-destructive behavior. The description adds 'Returns each item's numeric ID and name' and examples, which is useful but largely duplicates what the output schema likely provides. No extra behavioral context like ordering or completeness guarantees beyond 'all' is given.

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 exactly two sentences, front-loaded with the primary action and resource, and includes concrete examples without unnecessary padding. Every sentence adds value.

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

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

Given zero parameters, rich annotations, an output schema, and a simple list operation, the description fully covers the essential context: the resource domain, scope ('all'), and return contents. No critical information 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 tool has zero parameters, so there is nothing to describe. The baseline for zero-parameter tools is 4, and the description's 'all' confirms no filtering inputs exist, aligning with the empty input schema.

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

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

The description uses a specific verb ('List') and resource ('all gym equipment types in the wger database') and clarifies the returned data ('numeric ID and name'). This clearly distinguishes it from sibling list tools like list_exercises and list_muscles.

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 purpose implies the usage scenario (when you need gym equipment types), but it does not explicitly state when to prefer this tool over alternatives or when not to use it. No exclusions or alternative tool references are given.

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 signal read-only and idempotent behavior, so the bar is lower. The description adds transparency about the default limit of 20 and the language filter (English), which are not evident from annotations or schema.

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, with the main action stated first and supplementary details (default count, return fields) following. Every word adds value without fluff.

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

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

Given the tool's simplicity (one optional parameter), rich annotations, and existing output schema, the description covers all essential aspects: purpose, scope, return content, and default behavior. No significant gaps remain.

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

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

The schema already covers the single 'limit' parameter with full coverage. The description reinforces the default value but introduces no new syntax or semantics beyond the schema, aligning with the baseline for high schema coverage.

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

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

Description specifies the verb 'List' and the resource 'fitness exercises from the wger database', with a clear scope (English, optional limit). It differentiates from siblings like get_exercise by indicating a list of entries with multiple muscle and equipment fields.

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

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

The description provides clear context for when to use the tool (fetching a list of exercises from wger) and implicitly distinguishes it from more specific tools like get_exercise. It does not explicitly state exclusions or mention sibling alternatives, which prevents 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=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond annotations: it states the tool returns all muscles with specific attributes (numeric ID, English name, front/back location) and covers the entire wger database. 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?

Two concise sentences front-loaded with the primary action. Every word serves a purpose—scope, return fields, and location attribute. No redundancy or filler.

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

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

For a simple list tool with no parameters and comprehensive annotations, the description fully covers purpose, scope, and return fields. The presence of an output schema further reduces the need for additional explanation.

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

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

The tool has zero parameters, so the baseline is 4. The description provides no parameter details (none exist) and focuses on return values, which is appropriate for a parameterless tool.

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 ('List') and resource ('all muscles tracked in the wger database'). It also specifies the returned fields (numeric ID, English name, front-of-body flag), making it distinct from sibling list tools like list_exercises and list_equipment.

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 makes the usage context clear—listing all muscles—but does not explicitly mention when to use this tool versus alternatives (e.g., get_exercise). Use case is implied, not explicitly contrasted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable context beyond these by specifying the scope ('caller's') and the exact fields returned, which helps set expectations. It does not contradict the annotations.

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

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

The description is two sentences and front-loads the core purpose before giving usage guidance. Every word earns its place, with no repetition of schema information 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 read-only list tool with a single optional parameter and no output schema, the description is sufficiently complete. It covers the purpose, the return content, and the common use cases, which is everything an agent needs to know.

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 description coverage is 100%, as the single boolean parameter 'include_inactive' is fully documented in the schema. The description does not elaborate on this parameter, but the schema already does the heavy lifting, so a baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'List' with the resource 'subscriptions', scoped to 'the caller's active subscriptions'. This clearly distinguishes it from sibling tools like subscribe and unsubscribe, and it also lists the returned fields, 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 explicitly states when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This gives clear context and helps an agent decide between this and the subscribe/unsubscribe siblings.

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

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

Beyond the basic annotations, the description discloses rate limits (5 per identifier per day), the claim_token mechanism for follow-up, that it's free and doesn't count against quota, and how feedback is processed (daily digests). 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 dense paragraph packed with essential details. While front-loaded with purpose, it could be better structured into bullets or short sections for easier scanning. Every sentence earns its place, but readability suffers slightly.

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 4-parameter tool with no output schema, the description explains what the response will be (claim_token) and the lifecycle of the feedback. It covers scope, limitations, and follow-up procedure, making it self-sufficient 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 covers 100% of parameters, but the description adds practical guidance: how to use claim_token (pass with no other arguments), what to avoid in the message (don't paste end-user prompts), and how to describe context in terms of Pipeworx tools/packs. This goes beyond 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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by focusing solely on feedback about Pipeworx tools, not on data retrieval or 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 when-to-use guidance is given (bug, feature/data_gap, praise) and a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' It also tells users how to check if a tool is Pipeworx's.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: self-aggregating signal, derived from CF analytics-engine, no PII, and caching behavior (5min-1h). This fully discloses the tool's operational 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 four sentences, each contributing distinct value: what it does, what it returns, when to use it, and its data/caching characteristics. No redundancy or filler; it is front-loaded with the core purpose.

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

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

The tool has one optional parameter, no output schema, and rich annotations. The description covers return content (top tools, packs, volume), data source, privacy, and caching, which is fully sufficient for a simple, well-annotated read-only tool.

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

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

Schema coverage is 100% and the parameter description in the schema already explains the window enum and the trade-off between shorter and longer windows. The tool description repeats the same information without adding new semantics, so it meets the baseline expectation.

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 reports what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume. It distinguishes itself from siblings like discover_tools by focusing on real-time aggregated usage, not generic discovery.

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

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

Provides explicit use cases ('Useful for...') with three concrete scenarios, which is clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but the listed use cases are sufficient guidance for most situations.

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, and idempotentHint=true, but the description adds substantial behavioral detail beyond those: it discloses live CLOB depth fill-checking, specific thresholds (3pp deviation, 0.30 Jaccard similarity, 20% placeholder fraction), and the condition where realizable_edge_pp ≤ 0 means 'do not trade it'. It also mentions skipped_low_similarity and null signals, offering transparency without contradicting annotations.

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

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

Despite being long, the description is well-structured with uppercase section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode subheadings. Every sentence delivers operational detail, such as thresholds, response fields, and edge cases, with no repetition or filler. It is front-loaded with the core purpose and then systematically expands, making the length appropriate 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?

With no output schema, the description carries a heavy burden to explain returns, and it does so thoroughly: it specifies the response structure (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context) and the partition_check fields in event mode. It also covers failure and edge cases (placeholder filters, low-similarity rejections, thin legs), leaving no ambiguity for an agent to invoke the tool correctly.

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

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

The input schema provides descriptions for both event and topic parameters, achieving 100% coverage, which sets a baseline of 3. The description enriches this by explaining the full behavior of each mode: event walks child markets and checks date/threshold ordering, while topic searches related events and flattens markets. It also notes that full Polymarket URLs are accepted, adding value 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, actionable statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the resource (Polymarket), the action (find arbitrage), and the method. It also distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing distinct modes (trending_scan, event, topic).

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

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

The description gives explicit usage instructions for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is clear when-to-use/not-use guidance, exceeding a typical description.

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, yet the description adds substantial behavioral context: model family details, caching at KV level, diagnostics for empty segments, caveats about Fed signals being unreliable, and warnings that 'your edge may already be in the price.' This far exceeds annotation coverage and fully discloses behavior.

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

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

The description is long but highly structured with clear sections (model families, knobs, response top-level) and every sentence adds value. It front-loads the purpose and provides detailed behavior without redundancy. Complexity justifies the length.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It thoroughly describes by_segment contents, fed_candidates/fed_note, diagnostics, and how filters affect results. It also covers caching and parameter interplay, making the tool fully understandable for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning by explaining the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) in context of the response structure, and adds practical insights like slippage assumptions and 'set to 2 to require tight books.' This goes beyond the schema's descriptions.

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

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

The description clearly states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also explicitly distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by describing unique output segments and the 'what should I bet on today' 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 description provides strong context with 'Built for "what should I bet on today"' and explains when to use it versus alternatives via detailed tradeable-edge knobs and filtering behavior. However, it does not explicitly name alternative sibling tools or state 'use this instead of X,' leaving some implicit 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 (readOnly, openWorld, idempotent, non-destructive), the description discloses significant behavioral traits: snapshots are written on a cache-miss so gaps mean 'nobody scanned that day', history is bounded by a 60-day TTL, decay is computed from daily closes of edge_pp_net net of default slippage, and the value is signed by trade direction (negative = SELL YES). This is far beyond what annotations provide.

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

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

The description is dense but well-structured: purpose/analogy first, then args, then a detailed RESPONSE section, then LIMITS. Every sentence contributes valuable information (response field semantics, edge signing, snapshot gaps). The organization makes it easy to parse despite length.

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

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

With no output schema, the description fully compensates by detailing the response shape: tracked[] with trend and decay metrics, expired[] with lifespan_days, and snapshot_dates[]. It also explains caveats like 60-day TTL and daily-closes basis, covering all major behavioral aspects of a moderately complex telemetry tool.

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

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

The schema covers both parameters completely with defaults and valid values. The description adds only trivial repetition (e.g., 'window (snapshot family, default "1wk")') and provides no additional syntax or format details beyond the schema. Since schema coverage is 100%, the baseline of 3 applies without further compensation needed.

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

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

The description states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the question 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies using this to assess edge age/decay before trading, but does not explicitly name alternatives or state when not to use it.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantive behavioral detail: it walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; in basket mode it computes theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fills, thin_legs[], max_clean_notional_usd, and forced_directional_risk. It also warns about partial fills converting an arb into an unhedged directional position, going well beyond the annotation safety profile.

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

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

The description is long but well-structured with uppercase section markers (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the core purpose. Every sentence provides distinct information, though the length could be trimmed by removing some parallel phrasing between modes.

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

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

There is no output schema, so the description must enumerate return values; it does for both modes. It also covers defaults for side and size_usd, the clamp range, and the tool's intended place in the workflow relative to sibling tools. For a tool with 4 parameters, no output schema, and two distinct modes, the description is 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 schema has 100% coverage with detailed descriptions for each parameter. The description adds the critical constraint 'REQUIRES one of market (single-market mode) or event (basket/partition mode)' and clarifies size_usd's dual interpretation, though the schema already covers most parameter semantics. The added constraint is valuable for correct invocation.

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

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

The description opens with a clear verb-object: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by focusing on whether theoretical edges are actually capturable on the order book.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable, partial fills create directional risk). It names alternatives and provides a clear trigger.

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 readOnlyHint/openWorldHint/idempotentHint annotations, disclosing fee modeling limitations, gross vs net spread, the meaning of null temporal alignment, unclassified legs never being paired, and per-pair flags. There is no contradiction with the annotations.

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

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

The description is long, but it is front-loaded with the core purpose and modes, then organized with labeled sections for response, safety fields, flags, fees, and skipped counters. Every major block adds behavioral or return-value context that the absent output schema would otherwise need to provide.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so extensively: it covers response fields, compatibility codes, per-spread flags, temporal alignment semantics, fee disclaimers, and skipped comparison counters. An agent has enough information to invoke the tool and interpret its 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains that topic auto-fetches matching events, explicit ticker/slug overrides the mapped side, and both modes run the identical token-overlap matcher. This helps an agent choose and combine the parameters correctly.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is a specific verb and resource. It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, but the title and detailed mode descriptions make its distinct purpose clear.

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

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

The description gives explicit context for when to use topic mode versus explicit ticker/slug mode, and emphasizes that pre-mapped topics often return compatibility warnings rather than tradeable spreads. It does not explicitly state when to use a sibling tool instead, but the internal usage routing is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the list-all-behavior when key is omitted. It stops short of describing error cases, but annotation coverage lowers the bar.

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, then use cases, scoping, and sibling pairing. Every sentence contributes 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 covers purpose, usage context, scoping, and sibling relationships. It does not detail return formats, but the actions 'retrieve a value' and 'list all saved keys' sufficiently imply expected returns.

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

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

The input schema covers 100% of the single parameter with a clear description and example. The tool description merely restates what the schema already says ('omit the key to list all keys'), adding no new parameter-level detail 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 action: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly identifies the resource (saved memory values) and distinguishes from sibling tools by naming remember and forget.

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

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

Provides explicit when-to-use guidance with examples ('the user's target ticker, an address, prior research notes') and positions the tool among siblings via 'Pair with remember to save, forget to delete'. However, it lacks explicit when-not-to-use or alternative tool comparisons beyond remember/forget.

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, openWorldHint, idempotentHint, destructiveHint), the description discloses a key behavioral trait: setting mark_read:true flags returned events as read, affecting future pulls (only newer events). It also reveals the feed is persisted and shared via an HTTP endpoint. This is valuable context not captured in 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, front-loaded with the primary action ('Pull fired events'), and each sentence earns its place: purpose+returned fields, filtering+mark_read behavior, polling+alternative access. No filler or redundancy.

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

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

Given no output schema, the description compensates by summarizing returned fields (source, citation_uri, raw event payload) and covers the main parameters with examples. It also addresses polling psychology and provides a programmatic alternative. Slight gap: doesn't mention limit or unread_only, but those are well-documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by giving a concrete type example ('sec_8k'), explaining the 'since' filter as ISO timestamp with fired_at comparison, and detailing the side effect of mark_read:true on subsequent calls. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns the most recent alerts with specific attributes (source, citation_uri, raw event payload), and distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on alerts from the persisted evaluator feed.

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 usage context by noting 'Polls work fine' and offers an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, which helps choose between agent-polling and direct HTTP. However, it does not explicitly differentiate from sibling MCP tools or state when-not-to-use.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the fan-out behavior to multiple APIs, the GDELT→GNews fallback on rate limits/5xx, and the USPTO soft-fail due to PatentsView sunset. This gives the agent a realistic model of failure modes and data source behavior without contradicting annotations.

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

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

The description is front-loaded with intuitive query examples, then succinctly covers data sources, parameters, return format, and the key alternative. Every sentence adds valuable information with zero filler, striking an 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?

Although there is no output schema, the description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It also covers data source behavior, fallback, and edge cases (USPTO soft-fail), making the tool's behavior predictable in most situations.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters (type, value, since). The description adds no new parameter semantics beyond what the schema provides—it only repeats the since format and typical usage recommendation verbatim from the schema.

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

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

The description clearly states the tool is a change feed for a company over a time window, with explicit example queries ('What's new with X', 'latest on Y'). It distinguishes itself from entity_profile by specifying when to use the static profile instead, and the mention of multiple data sources (SEC, GDELT/GNews, USPTO) makes the scope 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 concrete usage context through example queries and recommends the default `since` value ('30d' or '1m'). It explicitly names entity_profile as an alternative for static profiles, providing clear when-to-use vs. when-not-to-use guidance.

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

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

Annotations already indicate this is a non-read-only, idempotent write, but the description adds valuable context beyond annotations: key-value storage scoped by identifier, session-specific retention (24 hours for anonymous, persistent for authenticated). 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?

Every sentence provides distinct value: purpose, usage triggers, storage model, persistence behavior, and tool pairing. The structure is front-loaded with the core action and efficiently conveys necessary details without waste.

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

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

Given the tool's simplicity (two required parameters, no output schema), the description fully covers what an agent needs: what to store, when to use it, persistence semantics, and related 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 description coverage is 100%, so the baseline is 3. The description repeats examples already present in the schema (e.g., ticker, address, preference) without adding new parameter-level meaning, so it does not exceed the baseline.

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

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

The description uses a specific verb ('Save data') and a clear resource ('data the agent will need to reuse later'), explicitly distinguishing it from siblings like recall and forget. It clearly states the tool's core function 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?

Provides explicit guidance on when to use it ('when you discover something worth carrying forward...'), and names companion tools ('Pair with recall to retrieve later, forget to delete'). Also clarifies persistence differences for authenticated vs anonymous sessions.

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/openWorld/idempotent annotations, the description discloses multi-endpoint cascades, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity handling via figi_candidates, and explicit unresolved fields. It also explains source labeling for each identifier without contradicting annotations.

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

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

The description opens with trigger phrases, then uses a clear two-type structure to deliver dense behavioral detail. It is long, but every sentence earns its place for a multi-source, multi-type lookup tool.

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

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

With no output schema, the description covers input semantics, source behavior, ambiguity outcomes, degradation, and return markers such as figi_candidates and unresolved. An agent has enough information to call the tool 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 coverage is 100%, and the description still adds substantial meaning: accepted input forms (ticker, CIK, ISIN, name), exact issuer-name guidance for bonds, the warning about trailing security-class words, and drug brand/generic examples. This goes well beyond the schema fields.

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

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

The description names a specific action—resolving a user-spoken name into canonical/official identifiers—and gives concrete trigger query examples. It also positions the tool as providing inputs for other tools, distinguishing it from profile/research siblings.

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

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

The description gives an explicit decision rule: 'Use FIRST whenever you have a name but need an ID,' plus concrete query patterns. It does not explicitly name sibling alternatives or state when not to use this tool, so it lacks full exclusion routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it invokes ai_visibility_check per entity, ranks results, and returns a specific structure (score, confidence, signal density). This goes beyond the annotations without contradicting them.

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

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

Two sentences, front-loaded with the main purpose. The first sentence states the action and process; the second provides the use case and return format. Every word earns its place, and there is no redundancy with the schema.

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

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

The tool has 4 parameters and no output schema, but the description compensates by specifying the output fields (score, confidence, signal density) and the invocation workflow. It covers the core behavior and use case sufficiently; minor details like error handling are absent but not critical here.

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

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

Schema description coverage is 100%, so the schema already documents all parameters, setting a baseline of 3. The description adds extra semantic value by explaining that the first entity is treated as the 'subject' for narrative, which is not in the schema. This justifies a score above baseline.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It details the process (probes each entity with ai_visibility_check, ranks by score) and the result (surfaces most/least recognized). This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly differentiates from the single-entity sibling by emphasizing 'multiple entities side-by-side,' but it does not explicitly state when not to use it or name alternative tools for exclusion.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while the rest still returns. This goes beyond annotations and sets accurate 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?

Single paragraph is information-dense and front-loaded with the core purpose and use case. It packs in many output field names and caveats, but each clause earns its place for a composite tool; minor lack of structural formatting keeps it from a 5.

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

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

No output schema exists, so the description compensates by listing exact summary fields, per-advisory detail, links, alternative versions, and failure behavior. For a complex multi-source read tool with two parameters, this is complete.

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

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

Input schema fully covers both params (package name with scoped support, version defaulting to latest). The description does not add significant new parameter semantics beyond the schema; it mostly restates the default and explains output fields, so baseline 3 is appropriate.

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

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

Description clearly states it is a composite check for deciding whether to add an npm package, aggregating license, advisories, version history, and bundle size from deps.dev and bundlephobia. This specific verb+resource+scope distinguishes it from generic scan tools like scan_competitor_ai_presence.

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

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

Explicitly tells the agent when to use: 'Use whenever an agent asks...' and gives a clear exclusion for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), meeting the when/when-not bar.

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, idempotent, etc.), the description discloses algorithmic behavior (BGE-base-en embeddings, cosine, 500-char overlapping windows), the 200K char cap with truncation flagging, and the inclusion of character offsets for verbatim verification. This is rich, non-obvious context that annotations don't 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 appropriately sized — one focused paragraph. It front-loads the core purpose, then efficiently packs usage context, pairing, algorithm, and edge-case handling into a few sentences. 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?

Despite no output schema, the description explains the return format (top-N passages with character offsets and similarity scores). It also covers the 200K truncation behavior and the practical use case. The tool is fully contextualized for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: it explains that 'text' should be a previously fetched record, gives example queries, and explains the 'top-N' behavior tied to limit. This elevates the parameter guidance above the schema alone.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes the tool from siblings by framing it as a post-fetch, passage-level retrieval tool, and explicitly pairs it with ask_pipeworx_grounded to explain its unique role in the workflow.

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

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

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This makes the intended usage and relationship to alternatives crystal 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 adds substantial behavioral context beyond the annotations: it explains OAuth requirements, SMS phone verification and the 10/day cap, webhook signing secret issuance, and auto-disabling after 10 consecutive failures. These details are not present in the annotations and significantly improve understanding of side effects and constraints.

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 and every sentence carries information, but it is a dense block of text covering multiple types and deliveries. Given the tool's complexity, it remains efficient, though the length prevents a perfect score.

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

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

For a complex tool with nested objects and no output schema, the description is remarkably complete: it covers all supported types, parameter shapes, delivery channels, authentication requirements, return value, and operational details like SMS caps and webhook signing. No significant gaps were found.

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, but the description enriches parameters with concrete examples, such as items:["5.02"] = officer change and params:{topic:"fed"}. It also adds critical caveats for delivery parameters (phone must be verified, webhook secret returned only once) that are absent from the schema descriptions.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream.' It also specifies the primary return value ('Returns the new subscription id') and enumerates supported types, making it distinct from siblings like list_subscriptions, unsubscribe, 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 provides clear context on when to use the tool, including a prerequisite ('Requires a Pipeworx OAuth account') and an exclusion ('anonymous + BYO cannot persist subscriptions'). It also details delivery options and highlights the always-on feed, suggesting how to consume alerts. However, it does not explicitly compare against alternative tools like recent_alerts for one-off reads, so it falls short of 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 disclose read-only, idempotent, and non-destructive behavior. The description adds meaningful context: returns categorized examples drawn from the live catalog, and that omitting topic gives the full spread while passing topic focuses. It doesn't mention pagination or response size, but for this tool the added behavioral detail is solid.

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?

Despite being a dense paragraph, it's front-loaded with the purpose, then usage, parameter behavior, and when-to-use guidance. Every sentence adds value and there is no fluff or repetition.

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

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

With one optional parameter and no output schema, the description fully covers what the tool does, what it returns, how to call it, and when to use it. It is self-sufficient for agent selection and invocation.

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

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

The schema covers topic with a description and allowed values (100% coverage). The description reinforces this and explains the semantic difference between omitting vs providing topic (full spread vs focused), with concrete examples like 'finance', 'pharma', 'betting', going 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 explicitly states the tool is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It clearly distinguishes from siblings by saying 'Use this FIRST' and naming meta-tools it helps you learn.

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 gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to use the optional topic parameter to focus, and references alternatives like ask_pipeworx and entity_profile.

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 (mutation, idempotent, non-destructive), the description adds concrete behavioral details: ownership enforcement, deactivation rather than deletion, and the impact on recent_alerts. These details are not present in annotations and greatly improve the agent's understanding of the tool's 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 only two sentences, with the action front-loaded and the key behavioral nuance in the second sentence. Every word earns its place with no fluff or repetition.

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

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

For a single-parameter mutation tool with annotations and no output schema, the description is fully sufficient: it covers the action, ownership constraint, lifecycle consequence, and points to a related tool. Missing explicit error handling is acceptable given the tool's simplicity.

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

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

The input schema fully documents the single parameter (subscription id returned by subscribe), and the description adds no further parameter-specific details. This meets the baseline for high schema coverage, but the description does not elevate parameter understanding beyond the schema.

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

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

The description uses a specific verb and resource ('Cancel a subscription by id') and clearly distinguishes from siblings by noting ownership enforcement and deactivation rather than deletion. This makes its purpose unambiguous and differentiates it from subscribe, 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 implies when to use it: to cancel a subscription while preserving historical events via recent_alerts. It also notes the ownership restriction, but it does not explicitly state when not to use it or name alternatives, so it falls short of fully explicit guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds crucial context beyond annotations: the could_not_verify verdict means the check did not happen and must not be treated as evidence, unsupported means no source exists, and the dual-path architecture (structured SEC EDGAR vs. grounded fallback) is revealed. This is exactly the kind of behavior an agent needs to know.

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 a minimal two-sentence summary but every section serves a purpose: query examples, purpose, routing, return values, and the critical could_not_verify caveat. It is appropriately front-loaded. Some redundancy exists between 'natural-language claim verification' and 'check whether...' but it remains efficient.

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

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

Since there is no output schema, the description fully compensates by enumerating the verdict values, mentioning the pipeworx:// citation and reasoning fields, and explaining the two failure modes (could_not_verify vs. unsupported). It also covers the internal processing paths and the tolerance semantics. This is complete for a tool with this complexity.

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

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

The input schema has 100% coverage; both "claim" and "tolerance_pct" have detailed descriptions, with tolerance_pct explaining default behavior and hallucination-detection usage. The description adds no new parameter-level semantics beyond what the schema already provides, so the 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 concrete natural-language query forms ("Is it true that…", "fact check"), then states the core function: natural-language claim verification against authoritative sources. It clearly differentiates from sibling tools by being a one-shot claim verifier with an explicit verdict enum, and even notes 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?

Provides an explicit trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains internal routing (financial vs. non-financial claims). However, it does not name alternative tools or explicitly state when not to use it, so it misses the full 'alternatives' bar.

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