lorem

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, so the safety profile is covered. The description adds valuable behavioral details: the default model is free Workers AI Llama-3.3-70b, Anthropic probing requires a BYO key with direct payment, and the return structure is disclosed. Minor gap: no mention of rate limits or result pagination, but the description exceeds the baseline.

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

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

The description is three sentences long, front-loaded with the core action and outcome, then moves to model options and costs, then return format, then use cases. Every sentence adds essential information with no fluff or repetition of schema field names. It is model-efficient and easy to parse.

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

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

Even without an output schema, the description discloses the return format precisely ('per-model {score, confidence, signals, raw_response} + a combined view') and covers default behavior, optional payment, and canonical use cases. With only one required parameter and clear optional flags, this is a complete operational picture for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the default worker-ai model, clarifying that _apiKey is passed directly to api.anthropic.com, and that context helps disambiguate common names. These details help the agent correctly populate parameters without needing extra inference.

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

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

The description opens with a specific action: 'Probe one or more LLMs for what they know...' and a measurable outcome ('score visibility (0-100) per model'). It clearly distinguishes the tool from siblings like scan_competitor_ai_presence by focusing on LLM knowledge probing and scoring. The mention of a default model and optional Anthropic probe makes the purpose even more concrete.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and pragmatic guidance on when to pass _apiKey ('to also probe Anthropic'). It doesn't explicitly warn against using this tool vs alternatives, but the use cases and model options give clear context for when it's appropriate.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds valuable behavioral context: it routes to multiple tools, returns stable pipeworx:// citation URIs, and notes it is 'one fast call' that works on every tier, going beyond what annotations provide.

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

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

The description is long but well-structured and front-loaded with the key directive ('PREFER OVER WEB SEARCH'). Each sentence earns its place by adding usage guidance, examples, or alternative routing, though it could be slightly trimmed without losing value.

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

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

Given the tool's complex role as a router and the absence of an output schema, the description thoroughly covers purpose, usage, alternatives, and return behavior (structured answer with citations). It also addresses edge cases like breaking news and provides concrete examples, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the single required parameter is fully documented with a description and examples. The description adds no extra parameter-level detail beyond what the schema already 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 the tool's function: it answers factual questions by routing to one of 5,462 tools across verified sources and returns structured answers with citation URIs. It uses specific verbs like 'routes' and 'returns', and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also provides when-not-to-use guidance by directing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, naming specific 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 provide read-only, open-world, idempotent, and non-destructive hints. The description adds context beyond annotations: it discloses the beta nature, the possibility of candidate routing improvements being enabled live, and that it currently matches ask_pipeworx exactly. It also notes there is no fallback and it is a full working router, which clarifies the operational state.

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

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

The description is information-dense but efficient, covering beta status, feature parity, current state, usage, and evaluation purpose in a few sentences. The redundancy of 'Falls back to nothing — this IS a full working router' adds emphasis but is slightly repetitive. Overall, it is well-structured and front-loaded with the key 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?

Despite no output schema, the description states that the response shape is identical to ask_pipeworx, which is useful given the universal router complexity. It also explains the experimental evaluation process and the absence of active candidates, providing sufficient context to understand when and how the tool behaves differently from its stable sibling.

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

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

Schema coverage is 100%: the six parameters are three aliases (q, text, input, query, prompt) and the main 'question' parameter, all documented in the schema. The description mentions 'same arguments' but adds no additional meaning beyond the schema, 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 it is a 'Beta version of ask_pipeworx' acting as a 'universal router' with the same 5,462 tools, arguments, and response shape. It clearly distinguishes from ask_pipeworx by its experimental nature, but the core action ('ask') is only implied by the name and reference to the stable tool.

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 it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also clarifies the current state (no active candidate) and that it is fully functional. It does not explicitly mention when to avoid it, but the experimental context implies using the stable version when reliability is prioritized.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behaviors: it returns a structured refusal when data doesn't directly answer, with specific refusal reasons; it uses ONLY the tool result, never external knowledge; and it costs an extra LLM call. No contradiction with annotations.

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

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

The description is relatively long but every sentence earns its place: purpose, mechanism, return structure, refusal semantics, and usage guidance. It is front-loaded with the primary purpose and remains structured, though slightly dense.

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

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

Despite lacking an output schema, the description thoroughly explains the return shape (answer, evidence, confidence, source, fetched_at, refusal_reason) and all refusal scenarios. It also covers cost comparison and high-stakes use cases, making the tool self-contained for an agent.

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

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

The input schema has 100% coverage with all six parameters documented as aliases for 'question', so the description adds no new parameter-level meaning. It does clarify that the question is in natural language and will be routed to fill arguments, but this is implied by the schema and the tool's purpose. Baseline 3 is appropriate.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' for high-stakes reads, with a specific workflow: routing through 5,462 tools, fetching data, and extracting answers only from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing the grounded extraction 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?

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and notes when to avoid it: 'prefer ask_pipeworx for casual lookups' because it costs an extra LLM call. This provides direct guidance on when vs. when-not, including a named alternative.

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

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

Annotations already mark readOnly=true, idempotent=true, and destructiveHint=false, so the safety profile is covered. The description goes far beyond this: it discloses parallel fan-out, low-confidence short-circuit status, closed-market handling, wide-spread tradeability warnings, resolution-rule cancellation risks, and news-fallback behavior. No contradiction with annotations; these are additive behavioral details.

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

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

The description is long, but it is organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Each section provides substantive guidance for safe and effective use. While not minimal, the density of critical behavioral information justifies the length for this complex tool.

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

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

With no output schema, the description carries the full burden of explaining return values. It thoroughly documents the evidence packet, market-vs-model comparison, resolver contract (match confidence/score/alternatives/suggestions), parent-event extraction, news fallback fields, and blocking safety statuses. This is comprehensive coverage of the tool's behavior and results.

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

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

Schema covers 100% of parameters (market, depth, include_raw) with clear descriptions. The description adds examples of market input formats and fan-out behavior, but does not introduce meaning for depth or include_raw beyond the schema. This matches the baseline for high schema coverage where structured data carries the load.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges and polymarket_arbitrage by emphasizing evidence aggregation and market-vs-model comparison. The input types (slug, URL, question text) and classifier list further nail 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?

It provides explicit usage context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear when-to-use guidance. However, it does not explicitly name alternatives or state when not to use this tool, only implying that other tools may fit other use cases.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No 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 dense and well-structured, leading with example queries, then core functionality, type-specific details, sorting behavior, and output. Some redundancy in the query examples could be trimmed, but each sentence contributes useful 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?

Given the tool's complexity and lack of output schema, the description is remarkably complete: it states return format (paired data + citation URIs), sorting order, data specifics, and handles nuanced cases like off-calendar fiscal years. All key aspects are covered.

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

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

The schema covers both parameters at 100%, but the description enriches the 'type' parameter by explaining that 'company' pulls 10-K financials and 'drug' pulls FAERS/FDA/trial data. This goes beyond the schema's minimal enum description, though the values array is adequately specified in the schema.

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

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

The description explicitly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, using specific verbs like 'compare' and 'rank.' It distinguishes itself from sequential single-pack lookups, making its purpose unambiguous and distinct from sibling tools.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete query examples and elaborates on what each 'type' retrieves, giving clear when-to-use and how-to-use instructions.

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 far beyond annotations by disclosing paid plan for 'thorough', the parallel decomposition behavior, gaps[] when unanswered, never-invented evidence, second-hop iteration details, citation_uri fetchability, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. No contradiction with readOnly/openWorld/idempotent annotations.

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

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

The description is long but every sentence contributes unique operational value, from account requirements to latency. It is front-loaded with the most critical constraint (account needed) and organized logically, though it could be tightened without losing 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?

Given the tool's complexity and absence of an output schema, the description thoroughly covers return values (findings packet with evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], and edge cases like semantically excerpting large records. It leaves no major operational aspect unexplained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: 'thorough' requires a paid plan, 'standard' and 'thorough' include contradictions[] scan, and it explains gap recovery behavior per depth. This elevates it above baseline.

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

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

The description clearly states the tool performs multi-source grounded research across Pipeworx's structured data sources, decomposing questions into facets and routing them to tools in parallel. It explicitly distinguishes itself from ask_pipeworx ('single lookup') and clarifies it is NOT open-web search, making its purpose and differentiation unmistakable.

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

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

Provides explicit guidance on when to use this tool ('Best for broad/multi-part questions over structured data') and when to use alternatives ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also states account requirements and fallback behavior if not signed in, which is 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?

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by revealing return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... no second schema lookup needed.' This goes beyond what annotations provide. It doesn't cover rate limits or auth, but those are less relevant given the read-only/idempotent hints.

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

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

The description is longer than average due to the domain list and return detail, but every sentence contributes. It is front-loaded with the core purpose and ends with a direct usage directive. No filler or repetition.

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

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

For a discovery tool, the description covers its input (natural language query), its output (top-N tools with schemas), and its recommended usage order. There is no output schema, but the description fully explains the return format. Combined with rich schema annotations, no gaps remain.

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

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

The schema has 100% coverage with explicit descriptions for all parameters, including aliases and examples. The description repeats some query examples but adds no meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'Find tools by describing the data or task,' specifying a clear verb and resource. It distinguishes this meta-tool from sibling data-specific tools by emphasizing discovery and returning ready-to-call tool schemas.

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

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

Explicitly states 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 and want to see the option set.' This provides clear context and implies alternatives (using specific tools directly).

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

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

Beyond the read-only, open-world, idempotent safety annotations, the description discloses valuable behavioral traits: this is a parallel fan-out across SEC, XBRL, USPTO, news, and GLEIF; it returns a specific structured payload with up to 5 recent filings and pipeworx URIs; it mentions the USPTO PatentsView API sunset with soft-fail and the GDELT→GNews fallback. These details significantly aid an agent in predicting results and handling failures, exceeding what annotations alone convey.

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?

Though the description is long, it is efficiently packed with high-value information and well-structured: it opens with trigger phrase examples, then states the core purpose, deduplicates with alternatives, and uses semicolons to list all return components. Every sentence contributes—no filler or fluff—and the critical fan-out/fallback details are front-loaded before the input instructions.

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 fully specifies the return payload including field names (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and even the patent API's status. It also covers input constraints, fallback mechanisms, and the parallel execution behavior. Given the tool's complexity (fan-out across multiple sources), this description is remarkably complete and self-contained.

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

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

The input schema already thoroughly documents both parameters with 100% coverage, including examples ('AAPL', '0000320193') and the names-not-supported caveat. The description's parameter-related text largely repeats this information (e.g., 'Pass ticker "AAPL" or zero-padded CIK'), adding no genuinely new semantic meaning. Thus the baseline score of 3 is appropriate, as the schema does the heavy lifting.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' with specific verbs like 'tell me about', 'research', and 'brief me on', making its purpose unmistakable. It explicitly distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', which helps an agent choose it correctly for holistic company queries.

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: 'ALWAYS PREFER ... when the user asks for a holistic view', and provides a clear alternative: 'names not supported (use resolve_entity first if you only have a name)'. It also specifies the exact input types (ticker or CIK) and notes the patents API's soft-fail behavior, leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already indicate destructiveHint and idempotentHint. The description adds context by specifying exactly what gets destroyed: 'a previously stored memory by key,' and mentions use cases like clearing sensitive data. This goes beyond the annotations to clarify the scope of the destructive action.

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

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

Two sentences effectively convey the action, usage context, and relationship to sibling tools. The description is front-loaded with the primary purpose and contains no unnecessary words or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description covers the functionality, when to use it, and how it fits with related tools. Annotations supply the destructive and idempotent behavior, so no additional details are needed. The tool is fully contextualized.

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 the key parameter already described as 'Memory key to delete.' The description simply reiterates 'by key' without adding new meaning or usage details beyond the schema. Baseline 3 is appropriate since the schema fully documents the parameter.

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 uses a specific verb (delete) and resource (memory), and distinguishes itself from sibling tools like remember and recall by specifying deletion as opposed to storage or retrieval.

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

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

The description explicitly provides 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 names sibling tools ('Pair with remember and recall') to clarify the workflow 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context: it fetches the page, extracts content, and emits a text blob in standard llms.txt format. This goes beyond annotations by describing the operational process and output shape, though it does not mention error handling or rate limits.

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: the first states the core function, the second explains the process, and the third lists concrete use cases. Every sentence contributes value with no redundancy or fluff. It is front-loaded with the key verb and resource.

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 parameters, simple output), the description is complete. It explains the input (URL), the process, the output format (single text blob ready to drop at site-root/llms.txt), and common use cases. No output schema exists, but the description explicitly covers what the return value looks like.

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 both parameters (url and max_links) have clear descriptions. The tool description does not add significant parameter-level detail 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 states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly explains what the tool does (fetches page, extracts title/description/key links, emits standard llms.txt markdown) and distinguishes it from siblings by focusing on producing an output file rather than analyzing or scanning.

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.' It does not name alternative tools or say when not to use it, but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context that the output is plain text without formatting, which is not captured by annotations. This goes beyond the baseline safety profile.

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

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

The description is a single sentence that front-loads the verb, resource, and use case, and adds the return format. Every word earns its place; there is no filler or redundancy.

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

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

The tool is simple with only two parameters and an output schema. The description covers the core purpose, use case, and return format, while the schema handles parameter details and examples. No significant information gaps remain.

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

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

Schema description coverage is 100% for both parameters ('count' and 'length'), including types, ranges, and enum values. The description adds no new parameter-level information, 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 uses a specific verb ('Generate') and resource ('placeholder text paragraphs'), with an explicit purpose ('for mockups and layout testing') and return type ('plain text without formatting'). This clearly distinguishes it from sibling tools like generate_with_options or generate_llms_txt.

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 clear context for when to use the tool ('for mockups and layout testing'), but does not explicitly mention alternatives or when not to use it. No exclusions are given, but the purpose is specific enough to guide selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that the output is HTML and that the text is placeholder content, providing useful context beyond the annotations without contradicting them.

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

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

A single sentence that is front-loaded with the main purpose and immediately lists the configurable options. No wasted words, every phrase earns its place.

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

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

The tool is simple (generation, no side effects) and benefits from strong annotations, a complete parameter schema, and an output schema. The description fully covers the tool's purpose and key options, 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?

Input schema has 100% coverage with detailed descriptions for all parameters, including examples. The description only reiterates the element options (headers, code blocks, lists) without adding new semantics beyond the schema, so a 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 a specific action ('Generate formatted placeholder text') and enumerates the distinct features (headers, code blocks, unordered/ordered lists). This distinguishes it from the sibling generate_paragraphs tool by highlighting the configurable elements.

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

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

The description provides clear usage context (when you need formatted placeholder text with specific elements) and tells the user to specify which elements to include. It does not explicitly mention alternatives or exclusions, but the sibling generate_paragraphs is implicitly the simpler choice.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it operates only on the caller's subscriptions, returns specific fields, and defaults to active subscriptions (implied by the include_inactive parameter). This goes beyond the annotations without contradicting them.

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

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

Two concise sentences: the first states the action and return fields, the second provides actionable usage guidance. Every sentence earns its place with no redundancy.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete. It specifies the operation, scope, return fields, and practical use cases, leaving no critical gaps.

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

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

Schema description coverage is 100% for the single parameter (include_inactive), so the schema fully documents it. The description adds no additional parameter-level detail, which aligns with the baseline of 3 for high coverage.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: 'the caller's active subscriptions'. It also lists return fields (id, type, params, created_at, last_fired_at, fire_count), distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. This implies when to use the tool but does not explicitly name alternative tools or state when not to use it, so it stops 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?

With no hints set (all annotations false), the description carries the burden and does well: it discloses rate limiting (5 per identifier per day), the fact that it's free and doesn't consume quota, that the team reads digests daily, and that signals affect roadmap. It doesn't describe the return value or whether submissions are acknowledged, which is a minor omission for a feedback 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?

Although the description is a bit long, every sentence serves a purpose: purpose, use cases, exclusions, content guidance, rate limit, cost, and roadmap impact. It is front-loaded with the core action and then logically expands, with no fluff or repetition.

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

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

For a simple feedback tool, the description covers everything an agent needs: what it does, when to use it, when not to, what to include, rate limits, and cost implications. The nested context object is explained in the schema, and the absence of an output schema is acceptable since this is a fire-and-forget feedback submission.

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

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

The schema already covers 100% of parameters with thorough descriptions, so the baseline is 3. The description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, which directly informs the message parameter. It also implies the 'context' param by referencing tools/packs/verticals.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the feedback categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by being the dedicated feedback channel.

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 by enumerating exact scenarios (bug, feature/data_gap, praise) and gives a strong exclusion: do not report issues with tools from other MCP servers. It even names the alternative action ('file it with that server instead') and clarifies the scope with 'Pipeworx tool names are the ones this connection lists.'

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the data source ('derived from CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h'). This adds non-obvious context about the tool's 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 well-structured: it opens with the core purpose, then lists use cases, then adds background notes on aggregation and caching. Every sentence adds value, and it is appropriately sized for the tool's moderate 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?

Even though there is no output schema, the description explicitly mentions the return contents ('top tools, top packs, and total call volume'), plus additional context like window semantics, caching, and privacy. Combined with strong annotations, this is a complete picture for an agent.

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

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

The single parameter 'window' is fully described in the schema, including the default and trade-off between windows. The tool description repeats the enum values but adds no new semantics beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now' and specifies outputs ('top tools, top packs, and total call volume'). It distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregated trending 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?

Provides explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs. However, it does not explicitly mention when not to use it or name alternative tools, so it's slightly below the full 5.

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

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

Even though annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds critical behavioral nuance: the fill check warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' It also details thresholds (Jaccard ≥0.30, >3pp deviations) and placeholder filters beyond what annotations provide.

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

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

The description is long but every sentence carries operational value. It is well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the primary purpose and mode selection before diving into details. No redundant or filler sentences.

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

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

With no output schema, the description must explain return values, and it does: it specifies that response includes 'opportunities[] (gap_pp, suggested_trade, reasoning...)' and in event mode 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also covers edge cases like null arb signals and skipped_low_similarity, making the tool self-contained.

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

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

The schema only gives brief parameter descriptions (e.g., 'A topic or seed question'), but the description enriches both parameters: it provides concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), states that full Polymarket URLs are accepted, and explains behavior like 'walks child markets' for event mode and 'searches related events' for topic 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 clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the resource (Polymarket) and the method, and it is distinct 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?

The description provides explicit usage patterns: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also directs users to 'polymarket_fill_risk' for custom sizing, acting as a clear alternative.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing internal model calculations, caching behavior ('Cached 1h at the KV level'), response diagnostics, and limitations (e.g., unreliable Fed signal). It also reveals that opportunities include a 24h-move warning when edge may be priced in, which is valuable 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 extremely verbose, packing in precise alphas (tennis 1.02, soccer 1.10, MMA 1.15), gate thresholds, and model formulas. While it is organized with numbered families and sections, it is not concise and could overwhelm an agent; much of the detail would be better placed in documentation or output schema.

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

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

Despite lacking an output schema, the description fully specifies the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics) and per-opportunity fields (edge_pp_net, kelly_fraction, etc.). It even explains why diagnostics exist, making the tool's behavior fully comprehensible.

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

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

Although the schema covers all 9 parameters (100% coverage), the description adds relational meaning by explaining how knobs interact, e.g., 'min_partition_leg_kelly filters partitions by best per-leg Kelly' and that partition arbs ignore min_kelly at parent level. It also clarifies slippage subtraction, enhancing the schema's individual field 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 clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further distinguishes the tool from siblings by naming three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with concrete examples, making its function 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 clearly states the intended use case ('Built for "what should I bet on today"') and explains how knobs like min_liquidity/max_spread_pp refine results. It does not explicitly name alternatives or exclusion criteria relative to siblings, but it provides strong contextual guidance such as why Fed bets are excluded from ranking.

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

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

The annotations already indicate a safe, read-only, idempotent operation. The description adds substantial behavioral context: source from daily snapshots, TTL limits, signed edge_pp_net values, snapshot gaps due to cache-miss behavior, and decay computed on daily closes. This exceeds the baseline and provides the agent with meaningful operational knowledge.

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

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

The description is long but information-dense; every sentence either clarifies the tool's purpose, explains response fields, or notes limitations. It is well-structured with clear sections for args, response, and limits, and avoids redundancy.

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

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

With no output schema, the description compensates by exhaustively detailing the response structure, including tracked[], expired[], snapshot_dates[], and their meanings. It also covers data freshness, snapshot gaps, and computational basis, making the tool's behavior and output fully predictable.

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 describes both parameters (days and window) with their defaults and clamps, so coverage is 100%. The description's prose repeats the defaults and adds 'snapshot family' context but provides little additional semantic value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering whether an edge is new or shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series history rather than current edge values.

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

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

The description provides clear context on when to use the tool (to understand edge age/decay and differentiate fresh vs stale opportunities). However, it does not explicitly cite alternatives or state when not to use it, such as deferring to polymarket_edges for current edges only.

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

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

While annotations already declare readOnlyHint=true, the description goes far beyond: it explains the tool walks the order-book ladder, returns detailed fill risk metrics, and warns about partial basket fills converting an arb into an unhedged directional position. This adds substantial behavioral context beyond safety hints.

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

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

Despite its length, the description is tightly structured: first sentence states purpose, then REQUIRES, then SINGLE-MARKET and BASKET modes with their respective inputs/outputs, ending with explicit usage guidance. Every sentence adds necessary information; no word is wasted.

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

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

With no output schema, the description carries the full burden of explaining return values, which it does thoroughly: it enumerates all outputs for both modes, including verdict values, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers parameter constraints and risks, making the tool's behavior fully predictable.

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, so the baseline is 3, but the description significantly enriches every parameter: it explains the difference between market and event modes, interprets size_usd differently for buys vs sells and for basket settlement notional, and clarifies the default side logic. This transforms the schema from bare enums into actionable guidance.

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 two modes (single-market vs basket) and explicitly names the sibling tools it complements, leaving no ambiguity about its 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?

It explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of not using it, providing clear context versus 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 annotations (readOnlyHint, idempotentHint, etc.), the description thoroughly explains behavioral nuances: compatibility_warning triggers, temporal_alignment implications, and skipped_cross_type/subtype counters. It also warns that pre-mapped topics are not necessarily tradeable, providing deep insight into the tool's limitations and edge cases.

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

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

The description is lengthy but structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and each sentence adds critical information about behavior, output, or limitations. It is appropriately detailed for the tool's complexity, though marginally verbose.

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

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

Given there is no output schema, the description compensates by detailing the response structure: leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment, and skip counters. It also covers edge cases and caveats, making the tool's behavior fully comprehensible.

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

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

The input schema already describes each parameter, but the description adds crucial semantics: the 'topic' parameter auto-fetches matching events, and explicit tickers/slugs override the mapped side. It clarifies the two modes and how they interact, significantly enriching what the schema alone 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 begins with a clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then details the two modes, response contents, and safety fields, making the tool's function unmistakable and differentiating it from siblings like polymarket_arbitrage by focusing on cross-venue comparisons and compatibility checks.

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

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

The description provides clear context on when to use the tool, including two distinct operating modes and explicit warnings that 'most pre-mapped topics return compatibility_warning today.' It doesn't name alternative tools, but it effectively communicates that the tool is for cross-venue spread analysis and that caution is needed, which is sufficient for correct usage.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: scoping to the caller's identifier and the dual behavior (retrieve single key vs. list all keys). It doesn't mention edge-case behavior like key-not-found, but that's minor given the strong annotation coverage.

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

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

Four sentences, each earning its place: the first gives the core action, the second the use case and benefit, the third the scoping constraint, the fourth the sibling tool relationships. No filler, and the main purpose is front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the core function, the list-all-keys variant, scoping, and how it interacts with remember/forget. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% (the 'key' parameter is fully described as 'Memory key to retrieve (omit to list all keys)'). The description reinforces this and adds concrete examples of what keys might be (user's target ticker, address, research notes), offering more semantic guidance than the bare 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 clear, specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It immediately distinguishes from related siblings (remember, forget) and gives concrete examples of what the tool retrieves.

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

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

It explicitly states when to use this tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the companion tools for the full lifecycle: 'Pair with remember to save, forget to delete.' This provides clear context 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?

The description explicitly states that setting mark_read:true flags returned events as read, which modifies the feed state. This directly contradicts the annotation readOnlyHint: true, which claims the tool is read-only. Per rubric, any such contradiction mandates a score of 1 and an annotation contradiction flag.

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 cohesive paragraph with no fluff. It leads with the action, then return value, filtering, mark_read semantics, and then the HTTP alternative. Every sentence earns its place and the structure is logically ordered 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 5-parameter tool with no output schema, the description covers the return payload, filtering, mark_read state changes, polling suitability, and a mirror endpoint. It relies on the schema for limit/unread_only but gives enough context for correct usage. The annotation contradiction is a notable inconsistency, but the description itself is fairly complete, so a 4 is appropriate.

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 all 5 parameters with descriptions (100% coverage), so the baseline is 3. The description adds valuable context by giving an example for 'type' (sec_8k), clarifying 'since' as an ISO timestamp, and detailing how 'mark_read' affects subsequent calls. This added meaning justifies a score of 4.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb and resource, clearly identifying the tool as an alert/event retriever. It further specifies the return contents (source, citation_uri, raw payload) and filter capabilities, distinguishing it from siblings like list_subscriptions and recent_changes.

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

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

The description provides clear usage context: it mentions polling works, gives an HTTP alternative (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, and explains filtering by type/since and mark_read for read tracking. However, it does not explicitly state when to avoid this tool in favor of siblings, 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?

Even though annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral detail: it fans out to three sources, explains fallback logic, notes the PatentsView API sunset and soft-fail, and discloses the return shape with grouped changes and citation URIs. 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 dense but well-organized: front-loaded with query intents, then source details, parameter guidance, and return shape. Every sentence adds useful information without redundancy, and it remains scannable despite its length.

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

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

This is a complex tool with multiple upstream data sources, fallbacks, and a soft-failing component. The description explains the output structure (changes[] by source, total_changes, pipeworx:// URIs), covers all three parameters' semantics, and gives enough context for an agent to decide when to use it. No output schema exists, so this narrative completeness is essential and achieved.

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

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

Schema already covers 100% of parameters with descriptions, but the description adds meaningful semantics: explains `since` relative shorthand ('7d', '30d', '3m', '1y'), provides concrete examples for `value` (ticker vs CIK), and reiterates that `type` only supports company. This adds value beyond the schema.

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

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

The description clearly states it is a change feed for a company over a recent window, with concrete example queries ('What's new with X'). It explicitly distinguishes from sibling entity_profile ('Use entity_profile instead when you want the static profile'), making the tool's specific scope unmistakable.

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

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

Provides explicit usage context: natural-language intents, one parallel call, source fallback behavior (GDELT preferred, GNews on rate-limit/5xx), and USPTO soft-fail. It also names the alternative tool entity_profile and even recommends a typical value for `since` ('30d' or '1m'), which is actionable guidance.

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

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

Annotations already cover readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: key-value storage scoped by identifier, persistence duration (24h for anonymous), and cross-session/within-conversation scope. It doesn't mention overwrite behavior, but the idempotent hint partially covers that. This exceeds the baseline while not being exhaustive.

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

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

The description is four sentences, front-loaded with purpose, then usage, then technical details, then companion tools. Every sentence adds distinct value with no redundancy or filler. It is efficiently structured for an AI agent to parse quickly.

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

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

For a simple two-parameter tool with no output schema and helpful annotations, the description covers purpose, usage, persistence, and companions. It lacks explicit details about return values or edge cases (e.g., overwriting an existing key), but those are minor given the tool's simplicity and the absence of an output schema. Overall, it is nearly complete.

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

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

Schema description coverage is 100%, with both 'key' and 'value' clearly described in the schema. The description adds minimal parameter-level detail beyond examples in the usage section, which reinforces but does not significantly extend the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear, specific verb and resource: "Save data the agent will need to reuse later." It explicitly distinguishes from siblings by naming recall (retrieve) and forget (delete), and provides concrete examples of what to store, leaving no ambiguity about the tool's function.

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 exactly when to use the tool: "Use when you discover something worth carrying forward" and lists example use cases. It also explains the pairing with recall and forget, and clarifies persistence conditions for authenticated vs anonymous sessions, giving the agent a full decision framework.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description goes beyond these by disclosing that each call cascades through several internal lookup endpoints, returns canonical fields (ticker, CIK, RxCUI, etc.), auto-disambiguates inputs, and provides citation URIs. This is valuable behavioral context not present in annotations.

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

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

The description is longer than typical but well-structured with bold labels and front-loaded examples. Every sentence contributes useful information, though some repetition exists in the example query phrasing. It could be slightly trimmed without losing value, but it remains focused and 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?

Given the tool's moderate complexity, rich annotations, and detailed input schema, the description provides complete context. It explains return values for each type (company vs. drug), accepted input formats, auto-disambiguation, and internal cascading behavior. The absence of an output schema is compensated by the description's explicit enumeration of returned fields.

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 enhances parameter meaning by explaining how 'value' is interpreted differently for each 'type' (e.g., company accepts ticker, CIK, or name; drug accepts brand or generic). It also enriches the 'type' parameter by describing the exact return payload for each supported type, which is not in 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's purpose: resolving user-spoken names to canonical identifiers. It uses a specific verb ('resolve'), identifies the resource (names to identifiers), and distinguishes itself from sibling tools by framing it as the prerequisite step for other tools requiring IDs. The inclusion of example natural-language queries reinforces purpose clarity.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types and explains that the tool replaces 2-3 manual lookups, implying when it is the appropriate choice. While it doesn't name specific sibling alternatives for exclusion, the directive 'Use FIRST' 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral context beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also discloses the output shape (ranked list with score, confidence, signal density). This enriches the agent's understanding of the tool's internal process and outputs.

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, followed by mechanism, use case, and output. Every sentence earns its place: the first states purpose, the second explains process, the third provides a concrete application and return format. No fluff or repetition.

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

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

Given the tool's moderate complexity (multi-entity probing, ranking), the description covers the main facets: what it does, how it works (via ai_visibility_check), when to use, and what it returns. It doesn't detail error handling or edge cases (e.g., entity limits), but with annotations clarifying safety and idempotency, the description is largely complete. The only minor gap is not explicitly noting the 2-8 entity limit (present in schema).

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

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

Schema coverage is 100% and each parameter has a description. The description adds no new parameter semantics beyond what the schema provides; it only mirrors the 'first entry as subject' rule (already in schema) and mentions 'N competitors' which is implicit in the entities array. This meets the baseline for high schema coverage without adding extra 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 opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking. The example query 'does Claude know about us as well as our competitors?' anchors the purpose in a concrete scenario.

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 when to use it: 'Useful for competitive AI-marketing audits' and gives a concrete example. It also implies the alternative (ai_visibility_check for single entities) by saying it probes each entity with that tool, though it doesn't explicitly say 'use this instead of ai_visibility_check when comparing multiple entities.' Clear context but missing explicit 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 readOnly, idempotent, non-destructive. The description adds substantial context beyond that: partial failures degrade gracefully, first measurement can take 5-30s, sources_failed lists timeouts, and the return summary block fields are enumerated. This gives the agent a detailed execution model absent from annotations.

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

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

Though dense, every sentence earns its place: purpose, use cases, return fields, and limitations. It is front-loaded with the core purpose and the structure is logical (purpose → usage → output → caveats). No filler or redundant repetition of schema details.

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

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

For a composite tool with no output schema, the description is remarkably complete. It describes the return block, per-advisory details, links, alternative versions, failure modes, timing, and ecosystem exclusions. There is no extraneous dependency on a missing output schema.

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

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

The schema already covers both parameters 100% (package name and version default). The description does not add additional parameter-specific meaning—it focuses on behavior and output. Per the rubric, when schema coverage is high, baseline 3 applies.

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

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

The description clearly states a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It distinguishes itself from siblings by detailing the fan-out across deps.dev and bundlephobia. The use-cases ('is X safe / popular / small' or 'what does adding lodash cost me') make the purpose unmistakable.

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

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

Explicitly provides when-to-use guidance: 'Use whenever an agent asks...'. It also gives a clear exclusion: 'NPM ecosystem only in v1' and points to an alternative for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Even covers partial failure behavior.

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

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

Annotations already declare read-only and idempotent behavior. The description goes beyond by disclosing the truncation cap ('longer inputs are truncated and flagged'), the internal mechanism (BGE-base-en embeddings + cosine over 500-char overlapping windows), and that each passage includes a character offset for verification. No contradiction with annotations.

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

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

The description is four sentences, each earning its place: core action, use case, sibling pairing, and technical caveat. It is front-loaded with the most important information and contains no fluff or repetition of schema details.

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

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

With no output schema, the description discloses the return format (top-N passages with character offsets and similarity scores). It covers purpose, usage, limits, and mechanism, making the tool fully understandable for an agent without needing extra context. It is complete for a read-only search tool.

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

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

The input schema has 100% coverage with detailed descriptions for all three parameters (text max length, limit range/default, query examples). The description adds no new per-parameter meaning; it only reiterates the 200K character cap. Thus baseline 3 is appropriate, as the schema does the heavy lifting.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which combines a specific verb ('search') with a clear resource ('a fetched record') and distinguishes it from siblings by the 'INSIDE' emphasis. It also specifies the return type (top-N passages with offsets and scores), making the purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides a direct alternative/complement in 'Pairs with ask_pipeworx_grounded', indicating when to use the sibling instead of the whole document. This is clear, actionable 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 adds significant behavioral context beyond annotations: OAuth account requirement, per-channel delivery details, SMS 10/day cap, webhook auto-disabled after 10 failures, and return of a webhook secret once. These details inform the agent about side effects and constraints that annotations (readOnlyHint=false, destructiveHint=false) don't fully cover. No contradiction with annotations.

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

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

The description is densely packed but well-structured with lists of types and delivery channels. It front-loads the core purpose and return value, then details each type and delivery option. Every sentence provides useful information, though it is somewhat long; still, it earns a high score for avoiding fluff.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers essential aspects: prerequisites, return value, subscription types with examples, and delivery channels. It lacks error behavior or how to manage subscriptions, but those are likely handled by sibling tools. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

Although schema description coverage is 100% and heavily repeats the same examples, the description adds interpretive value like 'items:["5.02"] = officer change' and emphasizes the proactive nature. It also clarifies the 'delivery' object's constraints (e.g., phone verification, 10/day cap) which are already in the schema but reinforced here. The extra semantics warrant a score above the baseline 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 clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return ('Returns the new subscription id'). It distinguishes the tool from siblings like 'recent_alerts' and 'list_subscriptions' by focusing on creation of subscriptions rather than retrieval or management.

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

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

The description provides clear context: it's for proactive monitoring, requires a Pipeworx OAuth account, and notes an alternative pull method (feed via 'recent_alerts or GET registry.pipeworx.io/alerts.json'). It also mentions prerequisites like phone verification for SMS. However, it doesn't explicitly contrast with alternatives like 'unsubscribe' or 'list_subscriptions', so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is known. The description adds value by explaining the output composition (category-bucketed examples with tool+argument shapes) and that it draws from the live catalog, which is not in 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 densely packed but structured: it opens with example queries, states the purpose, then details output, usage, and timing. Each sentence serves a distinct function, though the opening list could be trimmed slightly; overall it is appropriately sized for an onboarding tool.

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

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

With no output schema, the description adequately explains the return structure and purpose. It also provides context about the live catalog and meta-tools, making it complete for a simple one-parameter tool with rich annotations.

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

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

The schema already covers 100% of the parameters, fully documenting the optional `topic` parameter with allowed values and omission behavior. The description reinforces this with examples but does not introduce new semantic information, 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 clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by instructing to 'Use this FIRST' and by naming meta-tools to learn, making its unique purpose explicit.

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

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

The description explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides instructions on calling with no arguments or passing a `topic` to focus, which serves as clear usage guidance.

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

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

The description discloses important behavioral traits beyond annotations: ownership enforcement, deactivation rather than deletion, and that historical events remain available via recent_alerts. This adds substantive context about side effects and data persistence, complementing the annotations without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. It is concise and well-structured, covering the action, ownership rule, and deactivation behavior without waste.

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

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

For a simple mutation tool with one parameter, no output schema, and informative annotations, the description is complete. It explains the operation, the ownership restriction, the non-destructive nature, and the impact on historical data, leaving no critical gaps.

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

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

Schema description coverage is 100% (id is fully described as a uuid returned by subscribe). The description does not add further parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with a specific verb and resource, distinguishing it from siblings like subscribe and list_subscriptions. It includes the parameter (id) and key constraints, making the purpose unambiguous.

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

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

The description provides clear context on when to use the tool (cancel a subscription) and includes a constraint (ownership enforced) and a pointer to recent_alerts for historical data. However, it does not explicitly name alternatives like list_subscriptions or state when not to use this tool, 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already establish the safety profile. The description goes beyond annotations by explaining the internal pipeline (NL parsing → entity resolution → data lookup → comparison), the percent-delta math, and the fall-through behavior for non-financial claims. It also discloses the return structure (verdict, value, citation, reasoning). No contradiction with annotations.

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

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

The description is reasonably concise for the complexity, front-loaded with trigger phrases and a clear purpose. While the paragraph is long, every sentence contributes useful information (use cases, pipeline, output, efficiency benefit). It could be slightly tightened but is well-structured and 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?

Given the tool's complexity (two parameters, no output schema), the description is remarkably complete. It specifies the input types, the two routing paths, the return values (verdict, value, citation, reasoning), and parameter behaviors. The context signals confirm no output schema, and the description fills that gap thoroughly, making it sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% with both parameters documented. The description adds value beyond the schema by providing concrete examples for 'claim' and for 'tolerance_pct', explaining how tolerance overrides claim-implied defaults, and suggesting usage for hallucination detection (1-2%). This extra context enriches the parameter semantics without repeating schema content.

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 verifies natural-language factual claims, with specific verb ('verify', 'fact check') and resource ('claims against authoritative sources'). It distinguishes from siblings by focusing on claim verification with a verdict output, and details the two internal pathways (SEC EDGAR vs. grounded pipeline), making it uniquely identifiable.

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 whenever the agent needs to check whether something a user said is factually correct' and provides examples of when to use (company-financial claims via structured path vs. any other factual claim falls through). It lacks explicit 'when not to use' guidance or mention of alternative sibling tools, but the context is sufficiently clear for an agent to select this tool.

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