Medlineplus

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context beyond annotations: default model is free, using Anthropic requires a BYO API key with direct payment, and it discloses the return structure. This covers cost/auth implications and response format.

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: first states the action and output, second explains defaults and API key, third lists use cases. Every sentence earns its place, information is front-loaded, and there is no redundant 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 moderately complex tool with no output schema, the description covers the return values (per-model score/confidence/signals/raw_response + combined view) and payment/auth requirements. Combined with 100% schema coverage and strong annotations, the description is complete for an agent to select and invoke the 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining the cost implications of the _apiKey parameter and clarifying the default behavior of the models parameter. It helps an agent decide how to set parameters effectively.

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 ('Probe') and resource ('one or more LLMs') with a clear outcome (score visibility 0-100 per model). It clearly distinguishes from siblings by focusing on AI visibility scoring, and even provides example use cases.

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

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

The description states clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that imply when to use this tool. It does not explicitly exclude alternatives or name conflicting sibling tools, but the context is strong enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it fills tool arguments automatically, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. No contradiction exists, though it omits details about failure modes or rate limits, which the annotations already partially cover.

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: it opens with 'PREFER OVER WEB SEARCH', then enumerates data domains, the routing mechanism, trigger phrases, examples, and escalation paths in a logical order. Nearly every sentence adds decision-relevant information, though the specific tool/source counts and extensive example list make it slightly denser than strictly necessary.

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

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

For a default entry-point tool with no output schema, the description covers when to use it, what domains it spans, how it behaves, and what it returns ('structured answer with stable pipeworx:// citation URIs'). It is sufficient for correct invocation, though it could be more explicit about the exact output format or how ambiguities and errors are handled.

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 each parameter described as an alias for the natural-language question and the note 'Accepts query, q, prompt, text, input as aliases.' The description's examples like 'current US unemployment rate' and 'Apple's latest 10-K' reinforce natural-language usage but add no semantic information beyond the schema. Baseline 3 applies because the schema carries the heavy lifting.

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

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

The description explicitly states the tool 'Routes the question to the right one of 5,706 tools across 1493 verified sources' and returns answers with 'stable pipeworx:// citation URIs'. It clearly differentiates from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the default entry point over web search. This is a specific verb+resource with strong sibling differentiation.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases such as 'what is', 'look up', 'find', 'get the latest', and 'how much'. It also names concrete alternatives and conditions: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research'. Edge cases like breaking news are addressed as well.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, and the description adds important dynamic context: behavior may change as candidates are tested, currently no candidate is active, and it is a fully working router with no fallback. This discloses experimental status and live-property in a way structured fields cannot.

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

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

Four sentences, each carrying distinct information: definition, current status, usage instruction, and fallback clarification. Slightly repetitive (mentions identical/match twice) but remains tight and 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?

For a read-only routing tool with full schema coverage and annotations, it covers purpose, usage, current behavior, and fallback. No output schema exists, but the description at least indicates the response shape matches ask_pipeworx, which is sufficient context alongside that sibling tool.

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

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

Schema description coverage is 100% and each parameter (question plus aliases) is documented in the schema. The description merely restates that arguments match ask_pipeworx and adds no per-parameter semantics, 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?

Description explicitly identifies it as a beta version of ask_pipeworx, a universal router, and lists the shared scope (5,706 tools, same arguments, same response shape). It differentiates from the stable sibling ask_pipeworx by noting it carries candidate routing improvements, so an agent can tell which variant to choose.

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 an explicit use case: 'when you want the newest routing,' and says to use it exactly like ask_pipeworx. It also explains the current status (matches ask_pipeworx when no candidate is active) and the comparison/merge workflow, though it doesn't explicitly state when to prefer the stable router instead.

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

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

The description discloses the refusal mechanism with specific refusal_reason values, the exact success return shape including evidence as a verbatim quote, and the cost/behavioral difference vs ask_pipeworx. This goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive) and provides deep behavioral context.

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

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

The description is dense but every sentence adds value: mode definition, mechanism, return/refusal shapes, use cases, and cost tradeoff. It front-loads the core purpose and then supplies necessary detail 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?

With no output schema, the description adequately covers return values and error/refusal cases. It also covers behavioral tradeoffs and example domains. The tool is complex (routing, extraction, refusal logic) and the description provides enough operational detail for correct invocation.

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

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

The input schema has 100% description coverage, documenting the `question` parameter and all aliases (q, text, input, query, prompt). The description adds no additional parameter-level semantics, 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?

The description states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads' with a clear mechanism—routing, fetching, then extracting the answer only from the tool result. It also differentiates itself from ask_pipeworx by explicitly noting the extra LLM call and refusal 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' with concrete examples, and explicitly states when NOT to use it: 'prefer ask_pipeworx for casual lookups.' Also names the alternative (ask_pipeworx) and the tradeoff (one extra LLM call).

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 (readOnlyHint, idempotentHint, destructiveHint=false) already indicate a safe read operation. The description goes far beyond by disclosing fan-out behavior, resolver confidence (market_match_confidence), short-circuit statuses (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity handling, and resolution-rule risk with specific refund scenarios. This is exceptional 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 tightly structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads a one-sentence summary and then provides dense, necessary detail. Every section contributes to safe and correct usage; trimming it would risk losing critical information.

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

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

Despite having no output schema, the description fully specifies input formats, classification categories, fan-out logic, response shapes, resolver contract, parent-event extraction, news fallback fields, safety mechanisms, and resolution-rule edge cases. This is a model of completeness for a complex data-aggregation 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%, so the baseline is 3. The description adds practical examples for the 'market' parameter (slug, URL, question text) and clarifies the output size trade-off for include_raw. However, it does not elaborate on the 'depth' parameter beyond the schema, though the fan-out examples implicitly illustrate thorough behavior. Overall, it adds useful context beyond the raw schema.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings like ask_pipeworx (general Q&A) or polymarket_arbitrage by focusing on bet-specific data aggregation and classification. The intended input formats and output highlights are immediately stated.

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 the intended use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples across multiple categories. However, it does not mention when not to use this tool or name specific alternatives, so it stops short of the top score.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description details data sources (SEC EDGAR/XBRL, FAERS), specific metrics per type, handling of off-calendar fiscal years, sorting by primary metric, and output with paired data and citation URIs. This substantially enriches the agent's understanding of 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 structured for quick parsing: trigger phrases first, then core purpose, then priority instruction, then type-specific details, then sorting and output. It is dense but every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description covers the key aspects: range of entity counts (2–5), entity types, data sources, metrics, sorting, and output format (paired data + citation URIs). It also contextualizes the tool's efficiency ('Replaces 8–15 sequential lookups'), making it complete for the agent to select and use correctly.

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

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

Even though schema coverage is 100%, the description adds significant meaning: it explains that type='company' pulls specific financial data from 10-K filings and type='drug' pulls adverse-event counts, and clarifies that values are 2–5 tickers/CIKs or drug names with examples. This goes well beyond the schema's short 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 explicit trigger phrases and clearly defines the tool as 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from siblings by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups,' which separates it from entity_profile and similar 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?

Usage guidance is explicit: it lists trigger phrases like 'X vs Y' and 'rank these companies,' and instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This tells the agent exactly when to invoke this tool and when not to (instead of sequential lookups).

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, so the safety profile is clear. The description adds no extra behavioral context (e.g., behavior on unmapped codes, rate limits, or language handling) but is consistent with the annotations. It neither contradicts nor enriches the annotation-provided information.

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 sentence, front-loaded with the core purpose, and contains no unnecessary words. It is extremely concise while conveying the essential functionality.

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 presence of an output schema, the description needn't explain return values. It covers the main mapping function and the schema covers parameter details. It lacks mention of edge cases or language-specific behavior, but for a straightforward mapping tool with good annotations and schema, this is adequately complete.

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

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

Schema descriptions cover 100% of parameters, including the list of allowed code systems and the lang options. The description duplicates some of this information (e.g., code system list) but adds no new parameter semantics beyond what the schema already provides. Since schema coverage is high, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: mapping specific clinical code systems (ICD-10-CM, SNOMED CT, etc.) to MedlinePlus consumer-health topics. The verb 'Map' is specific and the resource is well-defined, distinguishing it from sibling tools like resolve_entity or compare_entities.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It simply states what the tool does without mentioning scenarios or alternative tools, leaving the agent without decision support.

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

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

Despite annotations already marking readOnly and idempotent, the description adds substantial behavior: parallel routing to thousands of tools, gaps[] for unanswered facets, never-invented findings, stable fetchable pipeworx:// citations, semantic excerpting, contradictions[] for certain depths, and expected latency. This goes well beyond the annotations and gives the agent 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?

The description is long but front-loaded with the most important decision cues: account requirement, fallback alternative, and structured-data scope. There is minor redundancy around citations (mentioned twice) and depth mechanics that overlap with the schema, but nearly every sentence contributes distinct operational knowledge.

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 two parameters and no output schema, this description is remarkably complete: it describes the findings packet fields, empty-result behavior, latency bounds, citation resolution guarantees, and depth semantics. An agent has enough information to invoke it correctly and to interpret the result plausibly.

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 extra meaning by clarifying that the question is natural-language and intentionally broad/multi-part, and by explaining depth's behavioral effect on hops and contradiction scanning. It does repeat some depth detail already in the schema, but it still enriches the question parameter's intent.

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, high-level operation: grounded multi-source research over Pipeworx's structured data catalog, with decomposition into parallel facets. It distinguishes itself sharply from open-web search and from the sibling ask_pipeworx, so an agent can tell what this tool uniquely does.

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

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

The description gives explicit when-to-use guidance: broad/multi-part structured-data questions. It also names exclusions and alternatives: single lookups and breaking/current-news topics should go to ask_pipeworx. Account-tier requirements are also stated up front, which is decision-relevant.

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

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

Annotations already cover safety (read-only, idempotent). The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, ready to call directly without a second lookup. It also advises calling this first, which is an ordering behavior 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?

Three sentences, front-loaded with purpose, and the domain list is packed but not wasteful. Every sentence contributes essential information.

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

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

Description explains what the tool returns, when to use it, and the breadth of domains. No output schema is needed because the description clearly states the response format. Sufficient for a discovery tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the query is a natural language description but doesn't need to add more since the schema already explains aliases and limits.

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

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

Description clearly states the tool's function: 'Find tools by describing the data or task.' It distinguishes from sibling tools by positioning itself as the first stop to see the option set, rather than retrieving specific data.

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

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

Explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' This provides clear guidance and differentiates from alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by detailing the fan-out across multiple sources, specific return fields (CIK, recent_filings, fundamentals, patents, news, LEI), and notable failure modes: 'USPTO PatentsView API sunset May 2025 — soft-fails until reactivated' and 'GDELT→GNews fallback.' This gives the agent essential behavioral expectations 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 a single dense paragraph, front-loaded with natural-language examples and then expanding into structured output details. It packs a lot of useful information—input format, return fields, fallback chains, and limitations—so every sentence earns its place. However, the length and run-on structure slightly reduce scannability; a bulleted breakdown would improve readability while retaining 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?

Given the tool's complexity (multi-source fan-out, multiple return types, no output schema), the description is remarkably complete. It explains what the tool does, when to prefer it (holistic requests), what it returns (CIK, filings, fundamentals, patents, news, LEI), how to pass input (ticker/CIK), what limitations exist (names not supported, patents sunset), and how failures are handled (soft-fail, fallback). This fully equips an agent to select and invoke the tool correctly.

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

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

Schema descriptions already cover 100% of parameters (type enum with description, value description including ticker/CIK and name restriction). The description adds valuable illustrative examples ('AAPL', '0000320193'), clarifies the zero-padding requirement, and reinforces the name unsupported rule in context. While the schema is already thorough, the description enriches understanding with concrete usage patterns.

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 begins with multiple user-phrased queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and states the core action: 'full cross-source profile of a US public company in ONE parallel call.' It clearly identifies the resource (US public company) and the output (profile across SEC/XBRL/news/etc.), distinguishing it from more targeted tools by emphasizing holistic coverage.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when NOT to use it: names are not supported, and instructs to 'use resolve_entity first if you only have a name.' This provides clear usage context and alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Delete' is not new information. It does add the context that it clears 'previously stored' data, implying it only affects existing memories, but this is a minor extension beyond the annotations.

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

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

The description is three short sentences that front-load the core action, then usage guidance, then sibling context. 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?

For a simple one-parameter delete tool with annotations covering safety and idempotency, the description fully covers the primary purpose, usage scenarios, and relationship to sibling tools. No output schema is needed, and no further context is required for an agent to invoke it correctly.

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

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

The input schema has 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'). The description only repeats 'by key', adding no additional semantics beyond what the schema already provides.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' It explicitly names the resource (memory) and the method (delete by key), and distinguishes itself from siblings by mentioning pairing with remember and recall, which are complementary functions.

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 guidance on when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also implicitly contrasts with alternatives by referencing remember and recall as companions, making the decision clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these annotations: it fetches the page, extracts specific elements, and emits a text blob in llms.txt markdown format. This clarifies the tool's internal process and output 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 three sentences, front-loaded with the primary action, then process details, then use cases. Every sentence contributes meaningful information with no redundancy or filler. It is well-structured and appropriately sized.

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

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

For a tool with 2 parameters, no output schema, and simple readOnly/idempotent behavior, the description is fairly complete. It covers input (URL), process (fetch and extract), output (single text blob), and scenarios. Minor gaps like failure handling or rate limits are not addressed, but they are less critical given the tool's simplicity and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond the schema; it mentions 'URL' generically and does not explain 'max_links' behavior. However, the schema already documents both parameters clearly, so the description adds minimal extra value here.

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: generating a production-ready llms.txt file for any URL. It specifies the verb 'Generate', the resource ('llms.txt file'), and the scope ('for any URL'), making it easily distinguishable from sibling tools that focus on auditing or checking AI visibility.

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: '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.' This gives clear context for when to use the tool, though it does not name alternative tools or explicitly 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 (readOnlyHint=true, destructiveHint=false) already establish safety. The description adds context by specifying the return fields and that it lists only active subscriptions by default, which aligns with the include_inactive parameter. It goes beyond the annotations by explaining the practical use case, though it doesn't detail pagination or authorization requirements. This is adequate for a shallow read-only tool.

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

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

The description is three sentences long, each serving a distinct purpose: stating the action, listing return fields, and providing usage guidance. There is no redundant or filler content. Information is front-loaded with the tool's core function.

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

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

The tool is simple: one optional parameter, no output schema, low complexity. The description covers the key behavioral aspects (what it lists, what fields return, when to use it). Since there is no output schema, listing the fields compensates for that gap. The description is fully sufficient for an agent to invoke the tool correctly without further clarification.

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

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

Schema coverage is 100% for the single parameter, so the baseline is 3. The description mentions 'active subscriptions' which hints at the default behavior of include_inactive, but this is already captured by the schema description ('Include cancelled subscriptions... default false'). No additional semantic meaning is added 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 starts with a clear verb+resource combination: 'List the caller's active subscriptions.' It specifies the scope (caller's own subscriptions) and distinguishes this from sibling tools like subscribe and unsubscribe by focusing on listing. The explicit enumeration of returned fields further reinforces the 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 third sentence provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and why, directly contrasting with subscribe/unsubscribe alternatives. It clearly implies when it is appropriate rather than the mutation siblings.

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

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

The description reveals key behavioral traits beyond the annotations: filing without an account returns a claim_token, can be passed back to read resolution status, rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. This adds meaningful context for the agent's decision-making.

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

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

The description is longer than typical but each sentence carries relevant information. It is front-loaded with the purpose, then flows through usage cases, exclusions, claim_token mechanics, and rate limits. Slight redundancy exists (e.g., 'Free; doesn't count against your tool-call quota' could be merged), but overall it is well-organized and not bloated.

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

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

For a tool with 4 parameters, nested context object, enum, and a claim_token return mechanism, the description covers all necessary aspects: usage, exclusions, token flow, rate limits, and quota impact. No output schema exists, but the description explains the return token, making the tool self-contained and complete for 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?

Although schema coverage is 100% and parameter descriptions are detailed, the description enhances semantics by instructing how to phrase feedback ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by illustrating the claim_token workflow ('Filing without an account returns a claim_token; pass it back later'). This goes beyond the schema's structured definitions.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist' with specific feedback types (bug, feature, data_gap, praise). This clearly identifies the tool's purpose and distinguishes it from siblings like ask_pipeworx or discover_tools, which serve different functions.

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 when a tool returns wrong/stale data (bug)...' and when not to use it: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This clearly delineates when to choose this tool over alternatives.

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

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

Beyond the strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, returns only (pack, tool, count), and has caching behavior (5min-1h). This fully discloses the operational characteristics.

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

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

The description is well-structured with a clear opening statement, numbered use cases, and a concise final line about the data signal. It is slightly longer than minimal but every sentence contributes substantive information. The front-loading of the core purpose is effective.

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

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

With no output schema, the description compensates by explaining the return content (top tools, top packs, total call volume, and the tuple format), the data source, caching, and privacy. It also covers the parameter's semantics and usage scenarios, making it fully sufficient for an agent to select and invoke the tool correctly.

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

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

The schema fully documents the 'window' parameter with an enum and description. The tool description adds interpretive meaning ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema. A 4 is appropriate because the schema already provides strong coverage and the description enriches it without redundancy.

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's function: reporting what other AI agents are calling on Pipeworx, with specific outputs (top tools, top packs, total call volume). It uses an active verb ('returns') and names the resource ('Pipeworx'), and the use cases distinguish it from sibling tools like discover_tools or search.

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 (discovering hot data sources, confirming canonical tools, checking alignment) and explains how the window parameter affects interpretation. It does not explicitly name alternative tools or state when not to use it, so it falls short of a 5, but the guidance is clear and practical.

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?

Goes well beyond the annotations by detailing internal logic: partition_check sum deviations >3pp emit a signal, semantic anchor with ≥0.30 Jaccard similarity, placeholder filter with >20% threshold returning null, and fill check behavior (theoretical vs realizable edge). No contradictions with annotations.

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

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

The description is dense but well-structured: opens with a clear summary, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize complex details. Every sentence contributes critical information without redundancy.

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

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

For a complex tool with no output schema, it fully describes response fields (opportunities[], partition_check), edge cases (placeholder fractions, thin_legs), and actionable warnings (realizable_edge_pp ≤ 0). It also points to a companion tool for sizing, making the description self-sufficient.

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

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

Although schema coverage is 100%, the description adds substantial context: for `event` it explains walking child markets and partitions; for `topic` it explains cross-event scanning and similarity constraints. This deeply enriches the schema's terse descriptions.

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

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

Description states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly identifying the tool's function and method. It distinguishes three modes (trending_scan, event, topic) and is differentiated from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan... pass event for... topic for...' with recommendations ('event (recommended for a specific market)', 'topic (for cross-event scanning)'). Also mentions exclusions: 'realizable_edge_pp ≤ 0 means ... do not trade it' and alternative tool 'For custom sizing use polymarket_fill_risk'.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description goes far beyond this by detailing the three segments, the diagnostics funnel, the 24h-move warning, the Fed note, the caching behavior, and the special handling of partition_overround (kelly_fraction_half=0 at parent level). It also explains that edge is net of slippage and Kelly is capped. There is no contradiction.

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

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

The description is long but highly structured with clear section markers: model families, response top-level, diagnostics, knobs, and caching. Every sentence conveys essential information—no fluff. The front-loading of purpose makes it immediately scannable.

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

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

With no output schema, the description takes on the burden of explaining return values, which it does thoroughly: by_segment keys, per-opportunity fields (edge_pp_net, kelly_fraction, etc.), diagnostics structure, and the Fed note. The 9-parameter tool is fully contextualized with rationale for each knob and the caveats around the models.

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, but the description adds substantial meaning. It explains the tradeable-edge knobs (min_liquidity, max_spread_pp), the interplay with min_kelly for partitions, the behavior of slippage_pp (Polymarket zero fees, typical 20-50bp), and why partition_overround ignores min_kelly by design. This richly augments 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 opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes this tool from siblings like polymarket_arbitrage by explaining the three model families and the stated purpose ('what should I bet on today'). The scope and unique value proposition are explicit.

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

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

The description gives strong context: it is built for discovering betting opportunities without paging hundreds of markets, and it mentions tradeable-edge knobs that help filter results. However, it does not explicitly contrast itself with alternatives or state when not to use it (e.g., for focused single-market analysis). This is clear context, but lacks direct exclusions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial context: history depth bounded by 60-day TTL, decay computed from daily closes not intraday, snapshot gap meaning, and detailed response semantics. No contradictions.

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

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

Description is long but well-structured with labeled sections (Args, RESPONSE, LIMITS). Every sentence earns its place, adding valuable detail without redundancy. The main purpose is front-loaded in the first sentence.

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 thoroughly documents the response structure (tracked, expired, snapshot_dates), their fields, and even caveats like history depth and decay calculation method. This is complete for a complex telemetry tool with no other schema support.

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

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

Schema covers both parameters completely with defaults and constraints (days clamp 2-30, window enum 24hr/1wk/1mo). The description repeats the same information without adding new meaning beyond what the schema already provides, 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?

Clearly states it provides edge persistence and decay telemetry built from daily polymarket_edges snapshots, answering a specific question about edge age and shrinkage. This distinguishes it from siblings like polymarket_edges, which likely provides current edges rather than historical persistence.

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?

Implies usage for evaluating whether an edge is stale or decaying, contrasting fresh vs 3-week-old edges and referring to median lifespan as a competition clock. Does not explicitly name alternatives or exclusions, but the context makes it clear when 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 already declare read-only and idempotent, but the description adds rich behavioral detail: it walks the order-book ladder, returns specific fields, explains the meaning of size_usd in different modes, and discloses that partial basket fills convert an arb into an unhedged directional position. This goes far beyond the annotations and provides essential risk context.

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

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

The description is long but every sentence earns its place. It uses clear structural markers (SINGLE-MARKET, BASKET) and bolded key terms, making it scannable despite its density. It is not padded with fluff; all content is directly useful for tool invocation.

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 carries the burden of explaining return values. It lists all key output fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, etc.) and even names the failure mode (forced_directional_risk). This is a complete picture 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?

The schema covers 100% of parameters, but the description adds significant meaning beyond the schema. For example, it explains that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, and clarifies side defaults. This gives the agent a deeper understanding of how to set parameters for each mode.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill-risk assessment rather than opportunity discovery or execution.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical edge is not capturable on thin books) and warns about partial-fill risks, giving clear when-to-use and when-not-to-use context.

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

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

Even with readOnlyHint, idempotentHint, and destructiveHint already declared, the description adds substantial behavioral detail: compatibility_warning and compatibility_codes can be non-empty even with matched pairs, unknown metric types are never paired, skipped counters are explained, and pre-mapped pairings are explicitly marked as keyword-matched rather than resolution-verified. This is rich, honest context that helps an agent interpret results correctly.

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

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

The description is long but densely informative, with clear visual signposts (TWO MODES, RESPONSE, SAFETY FIELDS) and no filler. Every section earns its place: mode selection, response shape, safety codes, skipped-pair behavior, and a practical caveat. The warning that most pre-mapped topics return compatibility_warning today is especially valuable and concisely stated.

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 goes beyond what is structurally provided by explaining response fields, top_spreads_pp, temporal_alignment, skipped counters, and all compatibility codes. It also covers practical pitfalls such as non-equivalent bet shapes and unverified premapped pairings. The only minor gap is behavior when no parameters are supplied, but the schema examples and required-parameters=0 context make this a small omission.

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

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

Schema description coverage is 100%, and the schema already lists the topic values, the override semantics, and example values. The description largely restates this, though it adds the high-level distinction between auto-fetched premapped events and explicit custom pairings. This is useful context but does not significantly go beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, and explicitly distinguishes this from single-venue tools by framing the delta as a real signal when bet shapes are equivalent. It also names the two operation modes, so an agent can immediately understand what resource is acted on.

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 context: two modes (`topic` shortcuts vs explicit ticker+slug), what each mode does, and a strong caveat that pre-mapped topics are often not tradeable and should not be trusted blindly. It does not explicitly name alternatives like polymarket_arbitrage or say when not to use this tool instead, so it falls just 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, idempotentHint, and non-destructive behavior. The description supplements this by revealing scoping details ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key argument to list all keys. It adds useful context beyond 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?

The description is three sentences, front-loaded with the primary action, and every sentence adds value: action, use case, and scoping/pairing. There is no redundant phrasing or unnecessary detail.

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

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

For a simple read-only memory tool with one optional parameter, full schema coverage, and safety annotations, the description covers all essential aspects: how to retrieve, how to list, scoping, and relationship to sibling tools. No output schema exists, but the tool's behavior is simple enough that return values are predictable; the description is complete for invocation.

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

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

Schema coverage is 100% with a clear parameter description ('Memory key to retrieve (omit to list all keys)'). The description adds illustrative examples of valid keys (user's target ticker, address, prior research notes) and explains the parameter's role in the remember/recall/forget lifecycle, enriching the schema's 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 states a clear verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It explicitly distinguishes from sibling tools by naming remember and forget, and provides concrete use examples (target ticker, address, research notes). This is a specific, actionable purpose.

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

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

The description gives clear context for when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, implying complementary alternatives. However, it does not explicitly state when not to use the tool or list other alternative tools for exclusion, so it lacks full when-not guidance.

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

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

The description states that mark_read:true flags events as read and changes future results, which is a stateful side effect. This directly contradicts the annotations readOnlyHint=true and idempotentHint=true, as the tool can mutate read state. Annotation contradiction is present.

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

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

Three sentences deliver the core purpose, return payload structure, filter options, side-effect behavior, and an external endpoint. The information is dense but not verbose, with every clause earning 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?

Without an output schema, the description explains the return fields (source, citation_uri, raw payload), covers all parameter behaviors, and discloses the mark_read side effect. It also addresses polling and script access, making it nearly complete for a read-oriented tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds examples (e.g., 'sec_8k') and clarifies semantics (since = fired_at >= time), but these are minor additions beyond the schema 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 the tool 'pulls fired events' from a subscription feed, with a specific resource and action. It is distinguished from sibling tools like list_subscriptions and recent_changes by focusing on the persisted alert feed and the evaluator-written events.

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 context for when to use it ('Polls work fine') and provides an alternative access method (HTTP URL for scripts/dashboards). However, it does not explicitly contrast with sibling tools or state when not to use it, so it slightly misses the highest bar for explicit alternative guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses fan-out to multiple external APIs, GDELT→GNews fallback on rate limit/5xx, and USPTO soft-fail due to PatentsView sunset. It also describes the return structure (changes[] grouped by source plus total count), providing rich behavioral context that annotations do not cover.

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

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

The description is compact but dense, front-loading purpose with example queries. All sentences carry essential information, but the single long paragraph with embedded clauses could be more scannable with bullet points. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (3 data sources, fallback logic, parameter formats), the description provides sufficient detail for correct invocation. It covers return format, parameter semantics, explicit alternative tool, and even notes the PatentsView sunset. No output schema is present, but the description compensates by describing the return structure.

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 all 3 parameters with descriptions, but the description adds practical examples for `since` (ISO/relative formats, suggested '30d'/'1m') and clarifies how the window applies to each data source. This adds value beyond the schema, though `value` and `type` are not further elaborated.

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

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

The description clearly states the tool provides a change feed for a company over a recent time window, listing specific sources (SEC, GDELT/GNews, USPTO) and explicitly contrasting with entity_profile. This distinguishes it from sibling tools like recent_alerts and entity_profile, demonstrating a specific verb+resource+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?

It provides natural language query examples ('What's new with X', 'latest on Y') and explicitly directs users to entity_profile for static profiles, giving clear when-to-use vs alternative guidance. This goes beyond implied usage by naming the alternative and the scenario for choosing 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?

Beyond annotations, the description discloses key-value scoping per identifier, persistence differences between authenticated and anonymous sessions, and a 24-hour retention window. These details add meaningful context about data lifecycle and access, which annotations only hint at.

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

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

Four sentences, front-loaded with the primary action, and every sentence adds value: purpose, usage examples, storage scoping, retention policy, and related tools. No fluff or redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema) and strong annotations, the description covers all necessary aspects: what it does, when to use it, how data is scoped/permitted, and how it relates to recall/forget. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not meaningfully elaborate on the parameters beyond calling it a key-value pair; the schema already provides clear examples for key and value.

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 saves data for later reuse, using a specific verb and resource. It distinguishes itself from siblings recall and forget by explicitly positioning itself as the store operation, making its 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. It also mentions pairing with recall and forget, which clarifies the complementary tool usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds rich behavioral context: cascading lookups across multiple endpoints (EDGAR, GLEIF, OpenFIGI, RxNorm), graceful degradation if GLEIF/OpenFIGI are unavailable, explicit declaration of unresolved identifiers, and the fact that a single call replaces 2-3 manual lookups. 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?

Description is front-loaded with action verbs and examples. It contains some verbose technical detail (GLEIF parent/ultimate-parent children, ISIN-to-LEI mapping) that could be condensed, but overall every sentence adds value. Slightly longer than ideal for quick scanning.

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

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

Given the complexity (cascading lookups, multiple identifier types, graceful degradation) and absence of an output schema, the description does an excellent job explaining what to expect. Minor gap: does not explicitly state that output format varies by type (company vs drug), though this is implied by the type-specific details.

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

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

Schema coverage is 100%, meaning parameters are fully documented in the schema. The description adds value by providing richer examples (ticker 'AAPL', CIK '0000320193', drug 'ozempic', ISIN 'CH0038863350') and explaining how the value parameter maps to different lookup behaviors depending on type. The description exceeds the baseline of 3 by adding practical context.

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

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

Description uses multiple clear verbs ('resolve', 'look up', 'find') with the resource ('entity name to official identifier') and distinguishes from siblings by naming specific scenarios (ticker, CIK, LEI, RxCUI lookups). Compare_entities and entity_profile exist as siblings but resolve_entity handles the initial name-to-ID conversion.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', provides examples of when to use (ticker lookups, drug name resolution), and implies alternatives (e.g., compare_entities for comparisons after resolution). Also notes supported entity types (company, drug) which helps the agent decide 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it makes multiple probes via ai_visibility_check, ranks results, and returns specific fields (score, confidence, signal density). This provides useful behavioral context beyond the safety annotations, though it doesn't mention potential rate limits or error handling.

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

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

The description is three sentences with information densely packed and front-loaded: purpose, behavior, use case, and return format. Every sentence earns its place with 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?

The tool has no output schema, but the description explicitly lists return fields ('ranked list with score, confidence, signal density per entity'). Parameters are fully explained in the schema, and the description provides the overarching workflow. It could mention the optional models parameter, but that is documented in the schema, so completeness is solid but not maximal.

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

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

Schema coverage is 100% and the schema already describes the 'entities' parameter including the first-entry-as-subject detail. The description does not add parameter-level semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states it 'Compare[s] AI visibility across multiple entities side-by-side' and 'Probes each entity with ai_visibility_check, ranks by score'. The verb+resource is specific and distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI presence ranking.

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

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

Provides clear context: 'Useful for competitive AI-marketing audits' with an example query. It implies when to use (multi-entity comparison) but does not explicitly name alternatives or state when not to use, 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 readOnly, idempotent, openWorld, and non-destructive. The description adds significant behavioral context: it fans out to multiple sources, handles partial failures gracefully, notes potential 5-30s delay on first bundlephobia measurement, and mentions the sources_failed field. This goes well beyond the annotations.

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

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

The description is longer than average but information-dense: purpose, usage, return fields, ecosystem limitation, and failure behavior are all present without padding. It is front-loaded with the core purpose. Slightly long but justified for a composite tool.

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

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

Given the tool's complexity and lack of an output schema, the description fully compensates by enumerating the summary fields, per-advisory details, links, alternative versions, and partial failure behavior. It covers ecosystem scope and timeout considerations, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100% for both parameters (package and version), so the schema already explains their meaning. The description does not add further parameter semantics beyond what is in the schema, meriting the baseline score of 3.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call' and clearly names the sources (deps.dev, bundlephobia) and the result fields. This unambiguously distinguishes it from sibling tools, which cover different research and monitoring tasks.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states the NPM-only scope and directs other ecosystems to 'deps.dev:version directly', giving clear when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the database scope (MedlinePlus/NLM) but does not disclose other behavioral traits such as pagination, result ordering, or potential limitations. This is comparable to a basic read operation with some context, but not rich.

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

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

The description is a single, concise sentence that is front-loaded with the key verb and object. It is free of redundancy and delivers maximum meaning in minimal space.

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, the presence of an output schema, and comprehensive annotations, the description is largely complete. It conveys the core function and scope, though it omits any usage guidance or mention of default behaviors, which are partially covered by annotations and 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 75% with descriptions for 'db', 'limit', and 'retstart'. The description adds minimal parameter context beyond what the schema provides, only implying that 'query' is a free-text search term. This does not significantly enhance schema understanding.

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

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

The description clearly states a specific action ('Free-text search') and resource ('MedlinePlus topics (or related NLM databases)'). It is not a tautology and gives enough detail to understand the tool's scope, though it does not explicitly distinguish itself from sibling tools like 'search_within'.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or comparisons to sibling search tools, leaving the agent to infer usage context.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses specific technical behavior: the use of BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagged, and the return format with offsets and similarity scores. This adds significant transparency 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 three sentences, front-loaded with purpose, then usage guidance, then technical details. Every sentence adds distinct value with no redundancy or filler, making it appropriately concise for the wealth of information it conveys.

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 must explain return values, and it does: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation at 200K chars) and the relationship with ask_pipeworx_grounded, making the description complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by giving concrete examples (SEC 10-K body, article) and clarifying that 'text' is a previously pulled record. It also explains 'limit' through 'top-N passages' and provides query examples, making the parameter semantics richer.

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

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

The description states a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from sibling tools by emphasizing 'inside' and positioning itself as a tool for large fetched records, contrasting with the broader 'search' sibling. It also names the output (top-N passages with character offsets and similarity scores), 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?

Explicit guidance is given: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded.' This tells the agent exactly when to choose this tool and how it relates to an alternative, fulfilling the when-to-use and comparison requirement.

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

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

Annotations already cover idempotency and non-read-only nature. The description adds valuable behavioral details: OAuth account requirement, feed always-on vs optional email/sms, phone verification requirement, and per-day SMS cap. These go beyond the schema and annotations, though webhook specifics are left to the 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 long but densely informative, with every clause earning its place. It front-loads the core purpose and then structures details by supported types and delivery channels. While longer than ideal, the complexity justifies the length; it is not wasteful.

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 subscription-creation tool with nested objects and multiple types, the description covers purpose, requirements, type-specific parameters, delivery options, and return value. It does not cover webhook behavior in the top-level text, but the schema delivers that. Missing error handling or idempotency details are partially covered by annotations, making this quite complete.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameter meaning with concrete examples for each subscription type (e.g., items:['5.02'] for officer change, topic:'fed' for polymarket_edge) and clarifies delivery channel semantics beyond the schema's already detailed 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 begins with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by framing this as the creation action, and explicitly notes it returns the new subscription id.

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 strong context on when to use: creating subscriptions to various event streams. It gives prerequisites (OAuth required) and implies alternatives by contrast with siblings, but does not explicitly state 'use list_subscriptions to view existing' or 'use unsubscribe to remove.' Still, the usage context is clear and actionable.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, which the description complements by detailing the return structure: category-bucketed example questions with exact tool + argument shape. It also discloses the optional `topic` parameter's effect and the source (live catalog). No contradictions with annotations.

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

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

The description is a single dense paragraph that packs a lot of information. It is front-loaded with example questions and includes all necessary usage details. While not overly verbose, it could be tightened slightly, but every sentence contributes value. Therefore it earns a 4.

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 only one optional parameter and no output schema, the description fully explains what to expect: category-bucketed questions, each with the tool and argument shape. It covers usage for both the no-argument full spread and focused topic queries, and places it in the workflow with 'use FIRST'. This is complete for the tool's purpose.

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

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

The schema description for `topic` has 100% coverage, listing the enum values. The description adds practical examples (finance, pharma, betting) and clarifies that omitting it yields a cross-category spread, which is not in the schema. This goes slightly beyond the schema, making the parameter semantics clearer.

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

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

The description clearly states this is the onboarding entry point that returns category-bucketed example questions and explains the tool's scope. It distinguishes itself from siblings by naming it as the go-to for learning what Pipeworx can do and how to call meta-tools. The specific verb+resource+scope (suggest questions for Pipeworx onboarding) makes it 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?

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools. This provides clear when-to-use guidance. It also explains that omitting `topic` gives a full spread and passing `topic` focuses the results, making the usage context complete.

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 valuable behavioral context beyond the annotations: ownership enforcement, deactivation instead of deletion, and the preservation of historical events via recent_alerts. This complements the annotation hints (non-read-only, non-destructive, idempotent) and gives the agent a clear picture of side effects.

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

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

The description is concise, two sentences, and front-loaded with the primary action. Every sentence provides meaningful information without unnecessary detail.

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

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

Given the tool's simplicity (one parameter, no output schema) and the presence of annotations, the description covers all essential aspects: purpose, usage constraint, and behavior. It is fully sufficient for the agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% coverage for the single parameter 'id' with a clear description. The tool description adds no further parameter-specific semantics, so the baseline of 3 applies.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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 useful context about ownership enforcement and the deactivation behavior, which helps the agent understand when to use the tool. However, it does not explicitly compare to alternatives like list_subscriptions or subscribe.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral details: the two internal pipelines, the meaning of each verdict, and a strong warning that could_not_verify means the check didn't happen and must not be used as evidence. This is rich, actionable context.

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

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

The description is long but highly information-dense. It fronts the trigger phrases, then systematically explains paths, outputs, edge cases, and rationale. Every sentence contributes, though it could be tightened without losing value.

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

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

Given there is no output schema, the description effectively outlines return values (verdict, actual value, citation, reasoning), explains error states (could_not_verify with verification_error), and defines unsupported. It also covers input semantics and performance benefits, making it fully complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds significant value: it provides concrete claim examples, explains tolerance_pct overrides the implied tolerance, recommends 1-2 for hallucination detection, and specifies the default cap of 5. This goes well beyond the schema.

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

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

The description clearly states the tool performs 'natural-language claim verification against authoritative sources' and provides concrete trigger phrases. It distinguishes itself from sibling tools by focusing on fact-checking with a defined verdict output, not generic search 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two routing paths (structured SEC for company-financial, grounded for others). It mentions replacing 4-6 sequential calls, implying it should be used instead of composing search/entity tools, but does not explicitly name an alternative to avoid.

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