uored

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

Annotations already cover safety traits (read-only, non-destructive, idempotent). The description adds value by explaining the random nature and the return content (name, type, price range), which goes beyond the annotations. No contradiction between description and annotations was found.

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, focused sentence that immediately conveys the tool's purpose and output. It is concise with no filler.

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

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

For a simple one-parameter tool with an output schema, the description sufficiently covers what it does and what it returns. It does not explicitly guide tool selection among siblings, but that is not essential for this straightforward tool.

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

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

The input schema already fully describes the 'participants' parameter with examples. The description repeats similar examples but adds no new semantic information, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Find a random activity for a specific group size' and specifies the return fields—activity name, type, and price range. This distinguishes it from the sibling 'random_activity' tool by emphasizing the group size requirement.

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

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

The description implies clear usage context: use when you need an activity for a specific number of participants. It provides examples of group sizes, indicating when this tool is appropriate, though it does not explicitly mention alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return fields and the 'random' behavior, but the randomness is also evident from the tool name. It does not clarify that repeated calls with the same type may return different results, which could be relevant for expectations.

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

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

The description is a single, front-loaded sentence that immediately states the core function and return values. There is no filler or redundancy; every word earns its place.

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

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

For a tool with one parameter, high schema coverage, and an output schema, the description is mostly complete: it states the purpose, input category examples, and return contents. However, the invalid example and lack of explicit note about result variability prevent a perfect score.

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

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

The schema already provides 100% coverage with a description and enum for the 'type' parameter. However, the description's example 'sport' is not in the declared enum (which includes cooking and relaxation but not sport), creating a misleading example that could lead to invalid calls. This adds negative 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 action ('Find a random activity'), the resource ('by category'), and what is returned (activity name, type, participants needed, price range). It distinguishes from sibling tools like activity_by_participants by focusing on category as the input, and from random_activity by implying category is required.

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

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

The description implies this tool is for when you have a category in mind, but it does not explicitly mention alternatives or when not to use it. Sibling tools like random_activity and activity_by_participants are not referenced, so the agent must infer usage from the description alone.

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 read-only, open-world, and idempotent behavior. The description adds meaningful context: the default free model (Workers AI Llama-3.3-70b), the cost implication for Anthropic (BYO key, direct payment), and the structure of the return payload (per-model {score, confidence, signals, raw_response}). No contradiction with annotations.

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

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

The description is three sentences, each serving a distinct purpose: stating the core function, explaining model/cost details, and listing return format plus use cases. It is front-loaded with the most important information and contains no filler or redundancy.

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

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

Given there is no output schema, the description compensates well by specifying the exact return shape. It also covers default behavior, optional Anthropic integration, and typical use cases. Minor gaps (e.g., rate limits, score calculation methodology) prevent a perfect score, but the description is sufficiently complete for a read-only probe tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the default model behavior and the cost implications of passing `_apiKey`, which goes beyond the schema's per-parameter descriptions. It could go further by elaborating on how 'context' impacts results, but it still adds meaningful semantic context.

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

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

The description clearly states a specific verb ('Probe') and resource ('one or more LLMs... score visibility (0-100) per model'), making the core function unambiguous. However, it does not explicitly distinguish itself from the sibling tool 'scan_competitor_ai_presence', which may cover a similar use case, so it falls short of the top score.

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

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

The description names concrete use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This provides clear context for when to use the tool. It lacks explicit exclusions or alternative tool recommendations (e.g., 'for competitor-specific checks, use scan_competitor_ai_presence'), so it doesn't earn a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial context beyond these: it reveals the underlying scale (5,366 tools, 1,396 sources), the output characteristic (structured answer with stable citation URIs), performance ('one fast call'), and tier compatibility ('works on every tier'). It also indirectly discloses a limitation by contrasting with ask_pipeworx_grounded's 'hallucination-resistant' property, implying this tool may be less evidence-rigorous. 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 long but every sentence earns its place: it opens with a high-priority directive ('PREFER OVER WEB SEARCH'), states scope, gives concrete examples, and then maps out escalation alternatives. It is front-loaded and well-structured, though slightly verbose due to the extensive enumeration of sources and use cases. It is appropriately sized for a complex router tool, but not as lean as the two-sentence ideal.

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

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

For a tool of this complexity (a router over thousands of sources), the description is impressively complete. It covers functionality, input format, output characteristics ('structured answer with stable pipeworx:// citation URIs'), performance, tier behavior, and explicit alternatives for edge cases. Since there is no output schema, the description's mention of the return format is sufficient. It also addresses non-factual queries like news and sports, making it fully contextual.

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

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

The input schema covers all six parameters with description coverage of 100%, explaining 'question' and the five aliases ('q', 'text', 'input', 'query', 'prompt') precisely as aliases. The description text does not add any parameter-level meaning beyond what the schema already provides, so the baseline of 3 applies. The schema itself is sufficient for invocation.

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

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

The description clearly defines the tool as a question router over verified sources, with a specific scope ('current or historical data: SEC filings, FDA drug data...') and an obvious distinct function: it 'routes the question to the right one of 5,366 tools across 1396 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from sibling tools by naming alternatives like ask_pipeworx_grounded and deep_research, so the purpose is unambiguous and well differentiated.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and a list of trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'). It also gives clear step-up alternatives: 'for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research', plus an edge-case note for breaking news. This is a textbook example of actionable usage 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful context: it is a live experimental router with no active candidate right now, falls back to nothing, and is a full working router. This clarifies the beta risk and current equivalence, which annotations do not convey. 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?

Four sentences, each adding necessary context: beta status, equivalence, usage guidance, and experimental caveat. It is front-loaded with the key fact (beta version of ask_pipeworx) and avoids redundancy. Slightly verbose in the middle sentence but still efficient.

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

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

For a simple single-required-param tool with full schema documentation and safety annotations, the description provides enough context: experimental nature, current state, relationship to stable router, and response shape parity. No output schema exists, but 'same response shape' partially covers return expectations. Complete enough 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 all six parameters documented as aliases for the required question field. The description adds no new parameter-level semantics, just reiterates that arguments match ask_pipeworx. Baseline 3 is appropriate since the schema carries full parameter meaning.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, a universal router with the same tool set and response shape. It distinguishes itself from the stable ask_pipeworx by its experimental routing improvements and current exact-match state. However, it relies on prior knowledge of ask_pipeworx rather than stating its core function (routing natural-language questions) directly.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives clear when-to-use context relative to siblings. It doesn't explicitly mention alternatives like ask_pipeworx_grounded, but the guidance is sufficient for the beta-vs-stable distinction.

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, openWorldHint), the description adds rich behavioral context: it knowingly returns refusals with specific reasons (e.g., not_in_source, no_tool_match), costs an extra LLM call, and uses only tool results. It also specifies the exact return format, which is not covered by 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 every sentence earns its place: it opens with the core value proposition, then details the process, return format, refusal reasons, usage guidance, and cost tradeoff. There is no filler or redundancy, and the structure is logical and front-loaded.

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

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

Given the tool's complexity (routing across 5,366 tools, grounding, refusal logic) and no output schema, the description is remarkably complete. It covers what the tool does, how it behaves, its limitations (cost, refusal cases), and when to use it. No critical operational context is missing.

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

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

While schema coverage is 100% and parameters are aliases for the same question, the description adds meaning by explaining how the question is used: it 'picks the right tool... fills arguments, fetches the data.' This goes beyond the schema's generic 'Your question in natural language' and clarifies the parameter's role in the tool selection process.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' with a specific verb ('EXTRACTS the answer') and resource (tool results). It explicitly distinguishes from the sibling ask_pipeworx by noting 'Same routing as ask_pipeworx... then EXTRACTS the answer using ONLY what the tool result contains,' making its unique purpose clear.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative 'ask_pipeworx' and advises 'prefer ask_pipeworx for casual lookups,' plus mentions the cost tradeoff of one extra LLM call.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, but the description adds substantial behavioral context: parallel fan-out to multiple sources, low-confidence short-circuit with status:'low_confidence_match', handling of closed/dead markets, illiquid wide-spread warnings, GDELT 429 fallback flags, and cancellation-rule parses. Every safety and edge-case behavior is disclosed, with no contradiction to the annotations.

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

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

The description is long but well-organized with clear labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loads the primary purpose in the first sentence. Each paragraph provides valuable edge-case guidance, though some sentences are repetitive and could be tightened, so it does not achieve a perfect 5.

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

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

Given the complexity of the tool and the absence of an output schema, the description is remarkably complete. It details the response shapes (market, analysis, evidence), resolver match confidence and alternatives, parent-event extraction, news fallback behavior, safety short-circuits, and cancellation-rule risk. An agent can reliably select and invoke this tool correctly based on this documentation alone.

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?

All three parameters have descriptive schemas with 100% coverage, so the baseline is 3. The description reinforces the input format (slug, URL, or question text) and gives rich fan-out examples, but does not add deeper parameter-level semantics beyond what the schema already provides.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' clearly stating the verb, resource, and scope. It further specifies the workflow (resolve market, classify bet, fan out to data packs, return evidence packet + comparison) and provides concrete usage examples, making it unmistakably distinct from sibling tools that track edges or arbitrage.

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

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

Explicitly states when to use the tool with examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and includes advisory guidance to inspect the resolver contract before trusting analysis. It does not name alternative tools or provide exclusionary 'do not use' cases, but the intended context is clearly delineated.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: data sources (SEC EDGAR/XBRL, FAERS), specific metrics pulled, off-calendar fiscal year handling, sorting by primary metric, and output including citations. No contradictions with annotations.

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

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

The description is dense but well-organized, with trigger phrases, core purpose, usage guidance, and type-specific details. Every sentence adds value, though the trigger phrase list makes it slightly longer than necessary. Still, it remains efficient 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 absence of an output schema, the description compensates by summarizing return values (paired data + citation URIs), data sources, sorting behavior, and coverage. It is fully sufficient for an agent to decide when and how 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 coverage is 100%, the description enriches both parameters: 'type' is explained with its enum values and what data each pulls, and 'values' is clarified with examples, constraints, and the 2–5 count. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's function: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides specific trigger phrases and distinguishes itself from sequential lookups and sibling tools like entity_profile.

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 ('when comparing entities') and strongly recommends it over sequential single-pack lookups ('ALWAYS PREFER'). It also clarifies the two entity types, making it obvious when each applies.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses many behavioral traits: account sign-in requirement, paid plan for thorough, latency expectations (15-60s, ~90s for thorough), parallel routing to 5,366 tools, gap reporting with 'never invented', semantic excerpting, and contradiction scanning. It also clarifies that it is NOT open-web search, a critical non-obvious 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 very long and densely packed with valuable information, but it is not front-loaded—the opening sentence is about account requirements rather than the core purpose. All content earns its place given the tool's complexity, yet the structure feels sprawling and could be reorganized to lead with the main function.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (findings packet with evidence, confidence, gaps[], contradictions[], citations), how second-hop iteration works, and expected latency. It also covers authentication, alternatives, and the structured-data scope, leaving little ambiguity for an agent invoking this complex tool.

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

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

The input schema already describes both parameters in detail (100% coverage), including depth-level semantics and question guidance. The tool description adds marginal value by mentioning the paid plan for 'thorough' and repeating depth behavior, but the schema already covers these; the enhancement is too small to move beyond 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 performs 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources' in a single call, using verbs like 'research' and specifying the resource. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, with example use cases like 'compare X and Y's regulatory + financial exposure'.

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 and when-not-to-use guidance: it says to use ask_pipeworx for single lookups and for breaking/colloquial current-news topics, and notes that unsigned-in users should use ask_pipeworx. It also explains the appropriate depth levels and the trade-offs between quick, standard, and thorough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it returns top-N relevant tools with full input schemas and curated examples, and explicitly says results are ready to call directly (no second schema lookup). This goes beyond the annotations and clarifies the output 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 four sentences, front-loaded with the core purpose, then lists covered domains, return format, and usage advice. Every sentence adds value; the domain list is informative without being verbose. It is well-structured and wastes no words.

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

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

For a discovery tool with many siblings and no output schema, the description is very complete. It explains the tool's purpose, when to use it, what it returns (names, descriptions, full schemas with examples), and that results are directly callable. It also gives concrete query examples, leaving the agent well-prepared to invoke it.

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%: all six parameters, including aliases (q, task, search, description) and limit, are documented with descriptions and examples. The description reinforces the query semantics ('Natural language description') and mentions 'top-N' but does not add meaning beyond what the schema already provides. 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 specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes this meta-tool from siblings by listing the domains it covers (SEC filings, FDA drugs, etc.) and framing it as a discovery/browse tool. The phrase 'Call this FIRST' reinforces its unique role among the 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?

The description explicitly states when to use it: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also implies when not to use it ('not just one answer'), but it does not name alternative tools directly or provide explicit exclusions, 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses specific behavioral traits: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), handles the USPTO PatentsView API sunset with a soft-fail, and uses a GDELT→GNews fallback. This adds concrete non-obvious context without contradicting annotations.

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

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

The description is a long, run-on paragraph with semicolons; it is dense but not scannable. It contains many relevant details but could benefit from bullet points or shorter sentences. It earns a pass because every clause adds information, but structure is mediocre.

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

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

Given no output schema, the description thoroughly enumerates return components (cik, filings with URIs, fundamentals, patents, news, LEI), includes limitations (USPTO sunset, name unsupported), and covers input formats. It is complete for a 2-parameter tool with heterogeneous external data sources.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds practical examples ('AAPL', '0000320193'), explains zero-padding, and explicitly states names are not supported. It enriches the schema's param descriptions with usage context.

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

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

The description clearly states it produces a 'full cross-source profile of a US public company in ONE parallel call' with specific verbs like 'profile', 'research', 'brief me.' It distinguishes from siblings by explicitly preferring this over chaining single-pack lookups and mentioning resolve_entity for name inputs.

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

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

It provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear alternative for unsupported inputs: 'use resolve_entity first if you only have a name.'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds context beyond the annotations by clarifying that this deletes stored memory and flags the privacy benefit of clearing sensitive data. No contradiction with annotations exists.

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 short, directly useful sentences. The first names the action; the second gives usage triggers and sibling context. No fluff or repetition.

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

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

For a single-parameter destructive tool with solid annotations (destructiveHint, idempotentHint), the description covers everything an agent needs: what to delete, why, and when. No output schema exists, but the description doesn't need to describe return values for such a simple operation.

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

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

The input schema fully documents the only parameter ('key' with description 'Memory key to delete'), so the description doesn't need to add much. It simply mentions 'by key', which aligns with the schema but adds no additional detail or nuance.

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 with a specific verb ('Delete'), a specific resource ('previously stored memory'), and a method ('by key'). It also differentiates from sibling tools like remember and recall by focusing on deletion.

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 tells the agent when to use the tool: when context is stale, the task is done, or when clearing sensitive data. It also names complementary tools (remember and recall), giving clear context on where this tool fits.

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 on the internal process (fetching page, extracting metadata, emitting standard format) and the output shape. It does not cover edge cases or rate limits, but the annotations lower the bar, and the added detail is meaningful.

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 main purpose, and every sentence adds value. It is concise, well-organized, and free of fluff.

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

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

For a simple two-parameter tool with no output schema, the description is complete: it explains the tool's function, process, output format, and typical use cases. Combined with the annotations, the agent has sufficient context 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 description coverage is 100%, so both parameters (url and max_links) are already well described. The description itself does not add additional parameter semantics beyond repeating the purpose, so it meets the baseline without exceeding it.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with specific actions (fetches page, extracts title/description/key links, emits standard markdown). This distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which focus on analysis rather than file generation.

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

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

Provides explicit use cases: getting a client's site indexed, drafting llms.txt for your own project, or auditing competitor visibility. This gives clear context for when to use the tool, though it does not mention alternatives or exclusions, which would merit a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful context by specifying the scope ('caller's subscriptions'), return fields, and the default of active-only subscriptions, going beyond annotation metadata.

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 purpose, and every word adds value. It avoids redundancy and is highly 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?

For a simple list tool with one optional parameter, strong annotations, and a listed return field set, the description is complete. It covers what the tool does, what it returns, and when to use it, requiring no further elaboration.

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 optional parameter 'include_inactive', and the description does not add extra semantic detail beyond the schema. Thus 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 starts with 'List the caller's active subscriptions', which clearly identifies the verb, resource, and scope. It differentiates from sibling tools like subscribe/unsubscribe by being a read-only listing, and lists return fields for specificity.

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 use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel'. It implies the alternatives (subscribe, unsubscribe) without naming them, making the usage context clear but not exhaustively exhaustive.

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 several behavioral details beyond the annotations: rate-limited to 5 per identifier per day, free and not counted against tool-call quota. It also explains that the team reads digests daily and feedback affects roadmap. Since annotations are all false, these disclosures are valuable, though the description doesn't describe the response/acknowledgment.

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

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

The description is compact and front-loaded with the core purpose. Each sentence adds unique value: what, when, how, and operational notes. No redundant or filler content.

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

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

For a feedback tool with no output schema and a simple input schema, the description covers purpose, usage criteria, message constraints, and rate limits. It's sufficiently complete to let an agent decide when and how to invoke it without missing critical context.

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

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

Schema covers 100% of parameters with descriptions, giving a baseline of 3. The description adds important guidance: describe issues in terms of tools/packs, and avoid pasting end-user prompts. This enriches the message parameter semantics beyond the schema, though the type and context parameters are already well documented.

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: telling the Pipeworx team about something broken, missing, or needing to exist. It's distinct from all sibling tools (e.g., remember, forget, subscribe) because none are for feedback, and it uses a specific verb ('Tell') with a clear resource (Pipeworx team).

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 lists when to use: bug, feature/data_gap, praise. Also gives a negative instruction: don't paste the end-user's prompt. Rate limit and quota notes further clarify operational constraints, making the usage criteria unmistakable.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses valuable behavioral details: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), exact payload shape ('just (pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This gives the agent a clear model of what the tool returns and its freshness.

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

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

The description is front-loaded with the core function, then a concise returns list, then a numbered set of use cases, and finally a compact technical note on data source and caching. Every sentence adds value, and the list format makes it scannable for an AI agent.

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

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

Given the tool has only one optional parameter and no output schema, the description is remarkably complete: it explains the output components (top tools, top packs, count), the temporal window options, the data source, privacy, and cache freshness. There is no missing information that an agent would need to invoke or interpret results correctly.

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

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

The input schema already provides 100% coverage, including the enum values and guidance that shorter windows surface hot trends while longer windows show steady-state demand. The tool description repeats the window options and adds no new parameter semantics beyond what the schema already documents, so it stays at the baseline.

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

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

The description opens with a specific verb ('What other AI agents are calling on Pipeworx right now') and clearly states outputs: top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like discover_tools and activity_by_type by focusing on aggregated trending signal rather than entity-specific or detailed activity.

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 three explicit 'Useful for' use cases, giving clear context on when to invoke this tool (hot data sources, canonical tool confirmation, alignment with agent needs). It does not explicitly say when not to use it or name alternatives, but the use cases are concrete 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, non-destructive, but the description adds substantial behavioral context beyond that: the semantic anchor (Jaccard ≥ 0.30), the partition placeholder filter, the >20% placeholder return-null rule, the response shape, and the crucial fill-check caveat that a realizable edge ≤ 0 means the opportunity is not tradable. No contradictions with annotations.

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

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

The description is long but highly structured: it front-loads the core purpose, then uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and clear mode-by-mode guidance. Every sentence carries operational or decision-relevant detail, and the length is justified given the tool's multiple modes and important fill-check caveat.

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

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

Despite having no output schema, the description fully explains the response shape (opportunities[], partition_check{} fields), the no-argument behavior, both parameter modes, filtering behavior, and the fill-check workflow. It also cross-references polymarket_fill_risk for custom sizing, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and both parameters already have descriptions, but the tool description adds significant meaning: concrete slug examples, accepted full URLs, the no-argument mode, and exactly how event vs topic change the scan behavior. This exceeds the baseline 3 for full schema coverage because the description enriches both parameters with operational semantics.

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

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

The description opens with a specific action—'Find arbitrage opportunities on Polymarket'—and names the two methods (monotonicity violations + partition-sum checks). It clearly distinguishes three modes (no-arg trending scan, event, topic) and even points users to a sibling tool (polymarket_fill_risk) for custom sizing, so there is no ambiguity about what this tool does versus alternatives.

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

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

Usage guidance is explicit and actionable: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan', and 'For custom sizing use polymarket_fill_risk'. It also states when event is recommended over topic, and distinguishes cross-event mode from single-event mode, giving the agent clear selection criteria.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by detailing response segmentation, model families, Kelly caps, 24h-move warnings, tradeable-edge knobs, diagnostics, and KV-level caching. It also explains why certain segments may be empty due to gate failures or knob filters. 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 long but well-structured, with named segments, parentheticals, and a clear flow: purpose, model families, response structure, and knobs. It front-loads the primary purpose and then dives into important details. While dense and possibly over-long, every sentence provides specific value for correct invocation and interpretation.

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—9 parameters, no output schema, and no nested objects—the description thoroughly covers the top-level response shape (by_segment, fed_candidates, _diagnostics), per-segment behavior, edge cases (Fed bets, partition Kelly), and why segments may be empty. Callers can anticipate return structure and tuning behavior without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful global context: it explains that min_partition_leg_kelly applies to per-leg Kelly because basket trades always return kelly_fraction_half=0 at the parent level, that min_edge_pp is evaluated net of slippage, and that tradeable-edge knobs drop opportunities where edge isn't realizable. This goes beyond the individual parameter descriptions.

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

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

The description opens with a specific verb+resource+scope: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes itself from sibling Polymarket tools by framing the use case as 'what should I bet on today' and by focusing on edge discovery rather than arbitrage or risk analysis.

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

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

The description clearly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This provides clear context for when to use the tool, but it does not explicitly mention when not to use it or name alternative sibling tools for contrasting scenarios.

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/destructive=false. The description goes beyond by disclosing the 60-day snapshot TTL, that decay is computed from daily closes net of default slippage, that history starts from when snapshotting was enabled, and how expired opportunities are defined. This adds substantial behavioral context beyond the structured 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 lengthy but well-structured with clear section markers (Args, RESPONSE, LIMITS). Every sentence carries functional information, and the core purpose is front-loaded. It is not overly verbose given the complexity of the response format and limits, though it could be tightened slightly.

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

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

Given the tool's complexity (time-series snapshots, TTL, missing-data semantics) and the absence of an output schema, the description fully covers the response structure (tracked, expired, snapshot_dates) and the key limits. It provides enough detail for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds minimal extra semantics: days 'lookback, default 14, max 30' (schema says clamp 2-30) and window 'snapshot family' with default. These enrich but do not substantially change understanding beyond the schema.

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

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

The description opens with a precise verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It immediately answers the specific question 'how long has this edge existed and is it shrinking?' and contrasts fresh vs. old edges, clearly distinguishing it from related sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

The description provides a strong usage context by explaining when edge persistence matters ('a fresh wide edge and a 3-week-old wide edge are different trades') and what the response reveals. It does not explicitly name alternatives but implies when to use this tool over siblings. It also states data-gap semantics ('snapshots are written when polymarket_edges runs on a cache-miss'), giving practical guidance for interpretation.

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 readOnlyHint/idempotentHint annotations, the description discloses substantial behavior: it 'walks the ladder,' returns specific fields per mode, identifies 'thin_legs[]' and 'forced_directional_risk,' and warns that partial basket fills convert an arb into unhedged positions. No contradiction with annotations, though it omits potential error/edge-case behavior.

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

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

The description is long but well-structured with mode headings (SINGLE-MARKET / BASKET) and dense field lists. It is front-loaded with the core purpose, and every section contributes needed detail. It is not overly verbose for the complexity, though it could be slightly tighter.

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 enumerates all major return fields for both modes, explains parameter interpretation, warns about risk behaviors, and connects to sibling tools. This gives an agent a complete mental model of when and how to use the tool, including potential failure modes.

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

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

Even though schema coverage is 100%, the description adds critical semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional S' in basket mode. It also explains side defaults and mode-specific interpretation, adding real value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates this tool from siblings like polymarket_arbitrage and polymarket_edges by positioning it as a pre-trade verification step, not a signal generator.

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

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

Explicit guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also states mode requirements (REQUIRES one of market or event) and explains the rationale (thin books are not capturable, partial fills create unhedged directional risk).

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

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

The description goes well beyond the read-only annotation by explaining response structure, safety fields, compatibility warnings, skipped comparison counters, temporal alignment, and the fact that pre-mapped topics often produce non-tradeable signals. It also clarifies edge cases where spreads are meaningless, providing substantial 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 long but highly structured and front-loaded with the core purpose, then modes, response shape, safety fields, and limitations. Every sentence adds useful detail for a complex tool, and the use of labels like RESPONSE and SAFETY FIELDS makes it easy for an agent 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?

Since there is no output schema, the description fully compensates by detailing the response structure: leg-by-leg prices, matched spreads, compatibility_warning, temporal_alignment, and skipped counters. It also covers usage limitations, making the tool's behavior well-specified for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the two-mode interaction: `topic` auto-fetches pre-mapped events, while `kalshi_event_ticker` and `polymarket_event_slug` override the mapped side for custom pairings. This clarifies how the parameters relate to each other beyond the individual schema descriptions.

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

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

The description clearly states the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes of operation. It is specific about the resource and functionality, but it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, so it misses the highest mark.

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 guidance on when to use the `topic` shortcuts versus explicit event ticker/slug pairings, and warns when spreads are not meaningful via compatibility_warning and temporal_alignment. It does not explicitly mention alternatives among sibling tools, but it gives strong contextual guidance on interpreting results and avoiding false signals.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds return field context ('activity name, type, participant count, and price range'), but the output schema already exists, so this is somewhat redundant. No additional behavioral traits such as randomness source or error handling are disclosed.

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 concise: two short sentences. It front-loads the primary purpose ('Get a random activity suggestion to cure boredom') and then lists the key return fields. No wasted 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?

Given the tool's simplicity, zero parameters, rich annotations (readOnly, openWorld, idempotent, non-destructive), and the presence of an output schema, the description is sufficient. It clearly explains what the tool does and what the user receives, making it complete for the given context.

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

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

The tool has zero parameters and the schema is empty with 100% coverage, meaning there are no parameters to describe. Per the rubric, a baseline of 4 is appropriate when no parameters exist; the description adds nothing about parameters because none are needed.

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

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

The description clearly states the tool's function: 'Get a random activity suggestion to cure boredom.' It uses a specific verb ('get') and resource ('random activity suggestion'), and distinguishes from sibling tools like activity_by_participants and activity_by_type by emphasizing randomness rather than filtering.

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 ('to cure boredom') and implies the tool is for random, unfiltered suggestions, but it does not explicitly mention alternatives or when not to use this tool. No exclusionary guidance is given, so usage is implied rather than explicit.

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; the description adds identity scoping (anonymous IP, BYO key hash, account ID) and the dual-mode behavior (retrieve vs list), going beyond the annotation 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?

Three sentences, front-loaded with the core action, then usage context and pairing. Each sentence adds distinct value 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?

With one optional parameter and no output schema, the description covers functionality, usage context, scoping, and related tools, making it fully sufficient 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 coverage is 100% with a well-described optional key parameter. The description adds concrete examples of what keys might contain (ticker, address, research notes), enriching the parameter's meaning 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 retrieves a value saved via remember and lists all saved keys when the key argument is omitted. This specific verb+resource distinction separates it from sibling tools like remember and forget.

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

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

It explicitly explains when to use: to look up previously stored context without re-deriving it, and pairs with remember to save and forget to delete. This provides a clear workflow and names 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 annotations (readOnly, idempotent, non-destructive), the description reveals that setting mark_read:true flags returned events read, making subsequent calls show only newer events—a state-changing side effect. It also discloses the availability of an external HTTP endpoint and the returned event fields, providing meaningful behavioral context.

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

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

Three tightly written sentences: purpose, usage extensions, and alternative access point. No filler; the most relevant information 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?

With no output schema, the description enumerates what each event carries. It covers filtering, state behavior, polling suitability, and the external mirror endpoint. For a read-only tool with five optional parameters, this is fully self-sufficient.

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

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

Schema descriptions already cover all 5 parameters (100% coverage), so a baseline of 3 applies. The description adds a concrete type example ('sec_8k') and explains the consequence of mark_read ('so the next call only shows newer ones'), elevating it slightly.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource pairing. It further clarifies the return content (source, citation_uri, raw event payload), distinguishing it from sibling tools that manage subscriptions (e.g., subscribe/list_subscriptions).

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

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

It states filtering by type and since, and explicitly notes 'Polls work fine' and points to an HTTP endpoint for scripts/dashboards, which gives clear usage scenarios. It does not enumerate when-not-to-use or alternative tools, but the feed context is sufficient.

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?

Although annotations already declare readOnly, openWorld, idempotent, non-destructive, the description adds valuable behavioral detail: it fans out to multiple APIs in parallel, handles rate-limit fallbacks, soft-fails for patents, and returns structured changes[] grouped by source plus citation URIs. It also specifies `since` accepts ISO dates or relative shorthand with examples, which is 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 every sentence serves a purpose: query patterns, core function, data sources with fallback, parameter formats, output structure, and sibling-tool pointer. It is front-loaded with the most useful information and remains readable despite its length. No fluff.

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

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

The tool is complex (multiple external APIs, fallbacks, soft-fails, date parsing) but the description covers all essential aspects: inputs, outputs, limitations, and alternatives. Since there is no output schema, it describes the return structure (changes[] grouped by source, total_changes, citation URIs). This is a complete and self-contained description.

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 already provides descriptions, but the description enriches meaning further: it explains `since` with both ISO and relative examples ("7d", "30d", "3m", "1y") and recommends "30d" or "1m" for typical monitoring. It clarifies `value` accepts tickers or zero-padded CIK with concrete examples. This goes well beyond the schema.

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

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

The description clearly states the tool's purpose: "change feed for a company in the last N days/weeks/months" with specific sources (SEC EDGAR, GDELT/GNews, USPTO). It uses a specific verb+resource+scope and immediately differentiates from sibling entity_profile by noting when to use that instead.

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

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

The description opens with natural-language query examples ("What's new with X", "what happened to Z this week") to signal when it's appropriate. It explicitly says "Use entity_profile instead when you want the static profile", providing an exclusion criterion. It also explains fallback logic (GDELT preferred, GNews on rate-limit/5xx) to manage expectations.

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 key behavioral traits beyond annotations: key-value scoping by identifier, persistence differences for authenticated (persistent) vs anonymous (24 hours) users, and the relationship with recall/forget. It does not mention overwrite behavior or failure cases, but adds significant context to the idempotentHint and destructiveHint 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: purpose, usage guidance, storage/persistence details, and sibling relationships. It is front-loaded with the core function and contains no unnecessary 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?

For a simple two-parameter tool with no output schema, the description covers what to store, when to use it, how persistence works, and how it relates to recall and forget. It lacks edge-case behavior like overwriting or error responses, but these are not critical for basic operation, making it 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?

The input schema already provides full descriptions for both parameters (key and value) with examples. The description adds general usage context (e.g., value types like findings, addresses, preferences) but does not add significant parameter-level semantics beyond what schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes from sibling tools by explicitly naming recall and forget as complementary operations, and specifies the cross-session versus within-conversation scope.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also explains how to pair with recall and forget. However, it lacks explicit 'when not to use' guidance or comparison with alternative memory strategies, stopping short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description correctly avoids restating those. It adds valuable context about internal cascading lookups, auto-disambiguation, and citation URI returns, enriching behavioral understanding beyond 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 well-structured: it opens with query examples, states the core purpose, then breaks down supported types with return details. Every sentence is informative and 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?

Since there is no output schema, the description thoroughly explains what each type returns, including source, format, and citation URI. It also mentions internal cascading and auto-disambiguation, providing enough context for correct invocation.

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

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

Schema coverage is 100% and the parameter descriptions are already detailed with examples. The description adds a few nuances (e.g., 'auto-disambiguated') but largely repeats schema content, so it meets the baseline but does not significantly elevate parameter understanding.

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

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

The description uses a specific verb ('resolve') and a clear resource ('user-spoken NAME to the canonical/official identifier other tools require as input'). It immediately distinguishes itself from sibling tools by framing it as the go-to when you have a name but need an ID.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID,' which gives direct guidance on when to use this tool. It also details supported types and how each call replaces multiple manual lookups, making the use case unmistakable.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds meaningful behavior: the probing mechanism (via ai_visibility_check), ranking by score, and output fields (score, confidence, signal density). It does not cover edge cases like rate limits or error handling, but with annotations covering safety, the added context is sufficient for a 4.

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 plus a quoted use case and output summary. It front-loads the core purpose, uses every sentence to add value, and remains readable without unnecessary jargon. Well-structured and appropriately sized.

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

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

No output schema exists, so the description correctly explains the return value (ranked list with score, confidence, signal density). It also covers the multi-entity comparison workflow and use case. It omits model selection details and API key requirements, but these are fully described in the schema, so the description is complete enough for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the 'entities' parameter (your brand + competitors) and the subject/competitor distinction, but these are already in the schema. It does not add new parameter insights beyond what the schema provides, hence no score above 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 a specific action ('Compare AI visibility across multiple entities side-by-side'), identifies the resource (entities), and distinguishes from siblings by mentioning it probes each entity with ai_visibility_check and ranks by score. The competitive audit use case and output specification leave no ambiguity about what the tool does.

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

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

Provides clear context for when to use: competitive AI-marketing audits, with a concrete example ('does Claude know about us as well as our competitors?'). It implicitly differentiates from ai_visibility_check by describing multi-entity comparison, but does not explicitly state when not to use or name alternative tools, so it falls short of a 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts while other data still returns. This describes failure modes and latency, which annotations do not cover.

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

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

The description is longer than ideal, but it packs in necessary details: the composite nature, what each source provides, return fields, ecosystem scope, and failure behavior. It front-loads the primary purpose in the first sentence and then organizes supporting details. Every sentence contributes, though the density might challenge skimming. Overall, it earns its length for a complex tool.

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

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

Despite having no output schema, the description explicitly lists the return fields: summary block keys, per-advisory detail, links, and recent alternative versions. It also covers edge cases like timeouts and graceful degradation. For a composite tool with two external dependencies, this is thoroughly complete and leaves little guesswork for the agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant semantics beyond the schema: it reiterates that package is an npm package name and version defaults to latest, which the schema already states. The only minor addition is implying both parameters are used in the composite check, but this is not essential. The description carries minimal extra meaning for parameters.

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

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

The description starts with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly identifies the tool as a composite check that fans out across deps.dev and bundlephobia, and distinguishes itself by scoping to the NPM ecosystem while noting that other ecosystems belong to deps.dev:version directly. This is unambiguous and differentiates it 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?

The description explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an alternative path for non-NPM ecosystems, guiding the agent away from this tool for PyPI/Maven/Cargo/Go. This is clear usage guidance with 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations, the description discloses specific behavioral details: returns character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagged. It does not contradict the annotations and adds meaningful context for how the tool operates.

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

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

The description is dense but every sentence adds value: purpose, usage scenario, companion tool, and technical/behavioral constraints. It is front-loaded with the core purpose and does not waste words. The structure flows logically from what → when → how, earning a 5.

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

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

For a tool with 3 parameters, full schema coverage, no output schema, and simple value semantics, the description is remarkably complete. It tells the agent what to expect (passages with offsets and scores), the operational limits (200K chars, truncation flag), and the embedding approach. There are no significant gaps in context for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds marginal value by giving example queries ('supply-chain risk', 'fiscal year 2024 revenue') and explaining the limit as 'top-N passages' with default 5, but it does not significantly enhance what the schema provides. 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 a specific verb-resource pair: 'Semantic search INSIDE a fetched record.' It specifies inputs (text plus natural-language query) and outputs (top-N passages with character offsets and similarity scores), distinguishing it from sibling tools like ask_pipeworx by focusing on searching within already-fetched text rather than grounding over whole documents.

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

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

The description explicitly says to use this tool 'when the record is too big to cram into the prompt' and explains the benefit: saves context and returns only relevant passages. It also provides an explicit alternative/complement: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and when-not-to-use guidance.

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

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

The description adds behavioral context beyond the annotations by stating that an OAuth account is required, defining delivery channel constraints (phone verification, 10/day cap), and noting the feed is always on. It stops short of explaining idempotency implications, but the annotation already declares idempotentHint=true, so the added context is valuable and non-contradictory.

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 structured, leading with the main purpose, then auth, types, and delivery. Every major aspect is covered, though some details (webhook) are only in the schema, making the description slightly longer than necessary for high-level understanding. Still well-organized and front-loaded.

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

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

Given the tool's complexity (5 types, nested params, delivery channels) and no output schema, the description covers the critical aspects: return value, auth, supported types, and delivery options. However, webhook delivery is omitted from the description (though covered in schema), and idempotent behavior is not explained, leaving minor gaps.

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

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

The input schema already has 100% coverage with detailed descriptions, so the baseline is 3. The description adds value by explaining that items:['5.02'] corresponds to an officer change, and by providing concrete examples for type/params combos, which aids correct usage beyond the schema's terse examples.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This specifies the action (create), resource (subscription), and output, distinguishing it from sibling tools like list_subscriptions and unsubscribe. It also enumerates supported subscription types with examples, reinforcing its unique scope.

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

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

The description provides usage context by noting the OAuth requirement and explaining the feed channel can be pulled via recent_alerts, implying alternatives. It does not explicitly direct users to list_subscriptions/unsubscribe for managing existing subscriptions, nor does it state when not to use this tool beyond the auth limitation. However, the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it returns category-bucketed examples, is drawn from the live catalog, and can be focused by topic. It does not contradict annotations and enriches understanding of what the tool returns and how it behaves.

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 slightly long but well-structured and front-loaded with example natural-language queries. Each sentence adds value: onboarding purpose, output content, parameter usage, and when-to-use. It maintains focus without excessive 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 its low complexity (one optional parameter) and no output schema, the description adequately covers what the tool does, what it returns, and when to use it. It could be more complete by showing an example output snippet, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already covers the single optional parameter 'topic' with a full description and list of allowed values (100% coverage). The description repeats this and adds an example ('finance', 'pharma', 'betting'), but does not provide additional meaning beyond 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 clearly states the tool's function: it returns category-bucketed example questions with the exact tool and argument shape for each. It also identifies itself as 'the onboarding entry point', distinguishing it from sibling tools like discover_tools and ask_pipeworx by specifying its unique role.

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: '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 indicates how to invoke (with no args for full spread or with a topic). However, it does not explicitly state when NOT to use it or name direct alternative tools.

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

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

Beyond annotations, the description discloses that the row is 'deactivated (not deleted)' and that historical events remain available via 'recent_alerts.' This adds meaningful behavioral context about side effects, complementing the idempotent and destructive hints.

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

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

The description is three sentences long, front-loaded with the core action, and every sentence provides useful information. There is no filler or repetition of schema content.

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

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

For a one-parameter tool with no output schema, the description covers the action, ownership constraints, and the soft-delete behavior. It sufficiently prepares the agent about what happens without needing additional details.

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

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

The input schema already fully describes the parameter: 'Subscription id (uuid) returned by subscribe.' The description adds no additional detail about the parameter beyond 'by id,' so it stays at the baseline for 100% schema coverage.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes the tool from siblings like 'subscribe' (create) and 'list_subscriptions' (list). The ownership enforcement further clarifies its scope.

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

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

The description explicitly states a when-not condition: 'you can only cancel your own subscriptions.' This tells the agent not to use the tool for other users' subscriptions. The deactivation behavior also implies that it is appropriate for canceling while preserving history, which guides 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?

The annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: the exact percent-delta math for financial claims, the fall-through to a grounded pipeline for others, and the output verdict set with citations. It stops short of covering auth or rate limits, but the added detail goes well beyond the annotation flags.

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 well-structured: the opening paraphrase list orients quickly, the two-path explanation justifies the tool's value, and the closing efficiency note is useful. Every sentence earns its place, though the first sentence is long and the text as a whole is on the verbose side.

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 present, the description fully compensates by listing the verdict types, actual value with citation, and reasoning. It also covers routing logic, parameter semantics, and use cases, making it complete for an agent to decide when to call this tool and what to expect back.

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%, so the bar for added value is raised. The description enriches tolerance_pct by explaining 'set 1–2 for hallucination detection' and that the default is implied by wording, which is not in the schema. The claim parameter is also given concrete examples in the description.

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

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

The description opens with natural-language paraphrases ('Is it true that…', 'fact check', 'verify the claim that…') and explicitly states that this is claim verification against authoritative sources. It clearly differentiates from siblings by focusing on returning verdicts (confirmed, refuted, etc.), a capability not provided by the research or comparison tools in the sibling list.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct', giving an explicit when-to-use trigger. It also explains the two routing paths (SEC EDGAR fast path vs. grounded pipeline), but it does not name alternative tools or provide explicit when-not-to-use exclusions.

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