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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond this: it discloses that the tool acts as a router/aggregator that fills arguments on the agent's behalf and returns stable citation URIs, works on every tier, and requires one fast call. This extra context about being a routing layer rather than a direct query tool is genuinely useful and does not contradict the annotations.

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

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

The description is long but information-dense — every sentence earns its place, front-loading the key directive (PREFER OVER WEB SEARCH) before the domain list. The escalation sentence is a run-on that buries the transitions to ask_pipeworx_grounded and deep_research, and the trigger-phrase list is somewhat redundant with the examples. It's more over-stuffed than poorly structured, slightly hurting parseability for an agent needing to scan quickly.

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

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

For a complex aggregator tool with no output schema, the description does a strong job: it covers source domains, trigger conditions, escalation paths, expected output format (structured answers with citations), tier compatibility, and news routing. It omits rate limits, cost details, and explicit failure behavior, but given the tool's breadth and the absence of an output schema, the description carries most of the burden well and is reasonably complete for agent decision-making.

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% — the schema thoroughly documents the single required 'question' parameter and its five aliases (q, text, input, query, prompt) with a clear description. The description adds marginal value with trigger phrases and examples that hint at question formulation, but it doesn't add syntax or formatting details beyond what the schema provides. At 100% coverage, the baseline 3 is correct since the schema does the heavy lifting.

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

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

The description states a precise verb (routes/questions), a resource (5,635 tools across 1,477 verified sources), and a concrete output (structured answers with pipeworx:// citation URIs). It enumerates the covered domains (SEC, FDA, FRED/BLS, USPTO, ATTOM, weather, clinical trials, news, stocks, crypto, sports, academic papers) and explicitly differentiates from siblings ask_pipeworx_grounded and deep_research. An agent can tell exactly what this does and what it is not.

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?

This is exemplary usage guidance. It instructs the agent to prefer this tool OVER WEB SEARCH, lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), provides concrete examples, declares it the default START HERE entry point, and gives explicit escalation rules: use ask_pipeworx_grounded for a hallucination-resistant single answer with confidence, use deep_research for broad/multi-part questions. No inference is left to the agent.

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. The description adds valuable context: it is a full working router, not a fallback, and that candidate routing improvements are enabled live only when under test, with the last retired on a specific date. This goes beyond annotations by explaining the experimental edge and comparison purpose, though it does not detail response behavior beyond stating it is identical to ask_pipeworx.

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, starting with the core purpose, then current state, usage guidance, and a clarifying note about being a full router. Each sentence contributes information, though it could be tightened by merging the retirement date and current-match statements. It is concise relative to the amount of context it conveys.

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

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

The description explains the tool's role, relationship to the stable version, and current behavior. It does not describe the output format, but references 'same response shape' as ask_pipeworx, which may be sufficient if the agent knows ask_pipeworx. Given zero output schema, a mention of what a response typically contains would improve completeness, but the description is otherwise thorough for a beta router.

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

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

The input schema has 100% coverage, with every alias explicitly described as 'Alias for question' and the primary parameter documented. The description adds nothing about parameter meaning or usage beyond what the schema provides. Baseline 3 is appropriate since the schema fully documents the single logical parameter.

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

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

The description explicitly states it is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It clearly distinguishes from the stable ask_pipeworx by its experimental nature and current exact match to it. The verb 'ask' and resource 'Pipeworx' are clear, and the sibling relationship is explicitly named.

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 it exactly like ask_pipeworx when you want the newest routing', and clarifies that results are compared against the stable router. It also explains when it exactly matches the stable version (when no candidate is active), giving clear context. Alternatives are implied by contrast with ask_pipeworx.

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 extensive behavior beyond the annotations: refusal mechanisms ('not_in_source'|'no_tool_match'|etc.), refusal reasons, reliance solely on tool results, and the cost implication. Annotations only tell readOnlyHint/openWorldHint/idempotentHint, but the description adds grounding details and error semantics, significantly enhancing agent understanding.

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: it front-loads the core promise ('Hallucination-resistant answer mode'), explains routing in one paragraph, gives the return shape in a compact bullet, and ends with usage guidance. Every sentence earns its place; there is 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?

Despite having no output schema, the description fully documents the success and refusal response structures, covers use cases, alternatives, and cost trade-offs. For a tool with a single required parameter and rich behavioral semantics, this is complete.

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

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

The schema already fully describes the question parameter and its aliases with 100% coverage. The description adds no additional meaning about parameters (e.g., format, length, style) beyond what's in the schema. Thus, the description does not improve on the schema's clarity, and the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' for high-stakes reads, differentiates it from 'ask_pipeworx' by describing the same routing but with a stricter extraction step, and specifies the exact output structure. It names the sibling tool 'ask_pipeworx' as the casual alternative, making the distinction explicit.

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

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

It explicitly states when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('for casual lookups'), and even notes the trade-off (costs one extra LLM call). This is textbook usage guidance with clear 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 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 readOnlyHint and openWorldHint annotations, the description adds extensive behavioral context: it is NOT open-web search, returns a findings packet with verbatim evidence, gaps[], contradictions[], stable citations, excerpting behavior, and latency expectations. It even notes when results may be mostly empty for non-catalog topics, ensuring agents have accurate expectations.

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

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

The description is dense and front-loaded with the most critical information (account requirement, alternative, core purpose). Every sentence contributes to agent decision-making, but the length is substantial; it could be slightly tightened without losing value. Still, given the complexity, the density is justified.

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

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

Covers everything an agent needs to decide and call correctly: prerequisites, alternatives, behavior, output structure, depth semantics, limitations, performance expectations, and how to interpret results. With no output schema, the description compensates fully by detailing the return features and citation handling.

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

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

The schema already documents both parameters well (question and depth with enum values). The description adds further semantic value by explaining that questions should be natural language and broad/multi-part, and elaborating on the depth levels' hop behavior and gap-recovery mechanisms, enriching beyond the schema.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's 1477 structured data sources in a single call, explicitly distinguishing it from open-web search. It names the specific use case (broad or multi-part questions) and differentiates itself from ask_pipeworx, making the purpose unambiguous.

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

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

Provides explicit usage direction: use this for broad/multi-part research, use ask_pipeworx for single lookup or breaking/current-news topics. It also specifies account requirements and the fallback for unsigned-in users, plus depth-level selection guidance. This is textbook-excellent alternative routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, 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?

Annotations are all false, so the description must carry behavioral context. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and guidance on describing issues without pasting user prompts. This far exceeds the minimal annotation hints.

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

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

The description is a single dense paragraph but every sentence carries operational value: purpose, trigger conditions, cross-server exclusion, claim_token lifecycle, and rate limit. It is front-loaded with the main verb and resource, and the length is justified by the tool's non-obvious usage patterns. Could be structured with bullets, but remains tight.

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

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

With no output schema, the description covers return behavior by mentioning the claim_token returned on filing and the status read later. It also covers prerequisites (none needed to file), error avoidance (don't paste user prompt), and operational constraints (rate limit, daily digest). The nested context object is documented in schema, and the description clarifies how to reference Pipeworx-specific tools. This is complete for a feedback 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 provides 100% coverage, describing every parameter including enum values, so baseline is 3. The description adds meaningful extra semantics for claim_token: it explains how to use it to read the status of a previous report, including the exact call pattern. This elevates the parameter guidance from schema-only to usage-oriented.

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

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

The opening sentence 'Tell the Pipeworx team something is broken, missing, or needs to exist' clearly states the verb and resource. The description enumerates feedback types (bug, feature, data_gap, praise) and explicitly distinguishes this from other Pipeworx tools like ask_pipeworx by framing it as a reporting channel. This uniquely identifies it among the long 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?

It explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a when-not: 'if the tool came from a different MCP server... file it with that server instead.' This excludes cross-server issues and names the alternative action.

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=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: cascading through multiple lookup endpoints, graceful degradation, and explicit handling of unresolved identifiers under an 'unresolved' key. It explains the resolution pipeline across EDGAR, GLEIF, and OpenFIGI, which goes well beyond annotation information.

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

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

The description is comprehensive but lengthy, containing several sentences of technical detail about each identifier source and fallback behavior. It front-loads with example queries which is good, but some detail could be tightened without losing meaning. Every sentence adds value, but the overall length sacrifices conciseness.

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

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

With no output schema, the description must explain return values. It does so by listing the identifiers returned (CIK, ticker, LEI, FIGI, etc.) and noting that unresolved identifiers are explicitly stated. It also covers graceful degradation. However, it does not specify the exact JSON structure of the response, leaving some ambiguity about format.

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

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

Schema coverage is 100% with both parameters described. The description adds value by providing concrete examples (ticker 'AAPL', drug 'ozempic'), explaining edge cases like ISIN resolving to legal entity via GLEIF, and clarifying acceptable input formats. While the schema already gives basic descriptions, the description enriches semantics with practical 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 the tool resolves a user-spoken name to canonical/official identifiers. It provides specific example queries ('What's the ticker for...', 'find the CIK for...') and lists supported entity types (company, drug). The purpose is distinct from siblings like 'entity_profile' and 'compare_entities' by emphasizing it is the first step 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also details what input formats are accepted for each type and explains graceful degradation. However, it does not explicitly state when NOT to use it (e.g., if you already have an ID) or compare directly to siblings beyond the 'FIRST' hint.

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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds crucial behavioral context: what could_not_verify means (verification_error, not evidence), what unsupported means (no source found), and an explicit warning not to treat could_not_verify as evidence for/against the claim. This materially helps an agent interpret results correctly.

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

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

The description is long but information-dense. It front-loads with user-intent phrasing, explains the routing logic, lists all verdict outcomes, and clarifies error semantics. Every sentence contributes; the structure is logical (start→routing→returns→caller caveats). Slightly verbose but justified for the complexity.

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

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

Even without an output schema, the description enumerates all possible verdict values, mentions the actual value plus citation, and explicitly describes the two non-verdict cases (could_not_verify and unsupported). It also notes performance benefits (replaces 4–6 calls). Complete for a complex verification 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% with detailed descriptions for both parameters. The tool description adds value by explaining tolerance_pct overrides the implied tolerance and is capped at 5 by default, and by giving examples for the claim param. This goes beyond the schema baseline.

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

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

The description opens with concrete natural-language query patterns ('Is it true that…', 'fact check') and states the core function: natural-language claim verification against authoritative sources. It clearly distinguishes from siblings by noting it replaces 4–6 sequential calls and by splitting the handling of company-financial vs. other claims, which is a strong differentiation signal.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides a clear decision path (SEC EDGAR fast path for company-financial claims, grounded pipeline for anything else). It lacks an explicit 'do not use when…' exclusion, but the guidance is strong enough to be above average.

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