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 establish read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context beyond those: it routes to sub-tools, fills arguments automatically, and returns structured answers with stable citation URIs. This helps the agent predict what happens when it invokes the tool without contradicting 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 information-dense and front-loaded with the most important routing guidance, but it is somewhat repetitive: 'Routes the question...' and 'Routes to verified tools' say similar things, and 'for most questions' is stated twice. The examples are valuable, but tighter editing would improve the structure.

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 simple input schema, rich annotations, and lack of output schema, the description is unusually complete. It covers when to use, when not to use, example queries, supported domains, routing behavior, and return format with citations. There is no essential missing context for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%: the only real parameter, 'question', is well documented, and all aliases are listed. The description adds usage examples and topic guidance, but does not provide additional parameter-level semantics beyond what the schema already covers. 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 identifies the tool as a router/QA system: it routes questions to one of 5,798 tools across verified sources and returns structured answers with pipeworx:// citations. It names specific domains and gives concrete example questions, making the purpose unmistakable. It also positions itself against web search, which helps disambiguate it from general-purpose search 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 says to prefer this tool over web search for factual questions, lists concrete triggers ('what is', 'look up', 'find', 'get the latest'), and provides multiple examples. It also states when not to use it: non-factual questions, math, code, and internal codebase questions. This gives the agent clear decision rules for 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds genuinely useful behavior beyond annotations: the router can change routing behavior live whenever a candidate is under test, and it currently matches ask_pipeworx exactly because the last candidate was retired. 'Falls back to nothing — this IS a full working router' usefully prevents the agent from treating it as a non-functional stub. 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?

Front-loaded with the core identity ('Beta version of ask_pipeworx: identical universal router'), then current status, usage direction, and comparison purpose. Some redundancy — the equivalence with ask_pipeworx is restated three times ('identical,' 'matches ask_pipeworx exactly,' 'IS a full working router') — but each repetition carries operational nuance (same tools, current state, not a stub), so nothing is truly wasted.

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

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

For a high-complexity universal router with no output schema, this covers the essentials: identity, current live state, why the beta exists, and how to use it. The main gap is that the response shape is only referenced as 'same' as ask_pipeworx, so the agent must already know ask_pipeworx's output envelope; as an explicit pointer this is acceptable, but it is still a deferral rather than a 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% — all 6 parameters (question plus five aliases q, text, input, query, prompt) are documented with descriptions. The description only adds the cross-tool pointer 'same arguments' as ask_pipeworx, which is marginal and doesn't elaborate on any parameter semantics 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?

States a specific verb and resource ('universal router'), quantifies scope (same 5,798 tools, same arguments, same response shape), and explicitly differentiates from the sibling ask_pipeworx by framing this as the beta/experimental edge. An agent can reliably distinguish it from ask_pipeworx and ask_pipeworx_grounded without inspecting schemas.

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

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

Gives an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains the results are compared against the stable router to decide merges. Lacks an explicit when-not-to-use case (e.g., prefer stable ask_pipeworx when routing consistency matters) and does not mention ask_pipeworx_grounded as a related alternative, so it stops short of full 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it returns an explicit refusal instead of fabricating an answer, includes a verbatim evidence quote, lists concrete refusal reasons, and discloses the extra LLM call. No contradiction with annotations.

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

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

The description is compact but information-dense, with the key concept front-loaded, followed by output behavior, refusal semantics, and usage guidance. Every sentence adds distinct value, and the structured refusal-reason list avoids vagueness.

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

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

With no output schema, the description compensates by fully specifying the return shape and refusal cases. It also explains the underlying routing behavior, the evidence guarantee, and when to prefer the cheaper sibling. An agent has enough context to invoke this tool correctly and interpret its result.

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

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

Schema coverage is 100%, so the schema fully documents the question parameter and its aliases. The description does not need to repeat parameter details. It adds no extra semantic info about the question argument, which fits the baseline-3 expectation 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 states a specific mode ('Hallucination-resistant answer mode'), identifies the resource (ask_pipeworx), and differentiates it from the sibling tool by emphasizing constrained evidence-based extraction. It is immediately clear this is the grounded variant of ask_pipeworx and not a generic lookup.

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 when to use it: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes use cases. It also gives an explicit exclusion: 'prefer ask_pipeworx for casual lookups' because this mode 'costs one extra LLM call.' This is strong routing guidance.

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

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

Annotations already declare 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?

Annotations already mark readOnly/openWorld/idempotent, and the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition, gaps[] with no invented answers, citation_uri resolvability conditions, contradictions[] behavior, excerpting semantics, and expected latency. 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?

Information-dense and front-loaded with the critical account requirement and alternative routing. The exact repetition of 'For a single lookup use ask_pipeworx instead.' is a minor redundancy in an otherwise well-structured description.

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 research tool with no output schema, the description fully covers input prerequisites, return packet contents, citation behavior, failure/gap handling, and performance expectations. An agent has everything it needs to invoke and interpret results correctly.

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

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

Schema coverage is 100%, and the schema already documents 'question' and 'depth'. The description adds meaningful depth semantics for 'standard' vs 'thorough' (gap recovery, lead-chasing, contradiction scans) and latency expectations, though 'quick' is only covered in the schema.

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

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

Description opens with a clear verb-resource pair: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and differentiates itself from open-web search and ask_pipeworx. It identifies the exact use case (broad/multi-part questions) and contrasts with a sibling lookup tool, so an agent can select it correctly.

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 (broad/multi-part questions over structured data) and when not to: single lookups should use ask_pipeworx, and unsigned-in users should use ask_pipeworx. This is direct alternative routing with exclusion conditions.

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?

Despite readOnlyHint and idempotentHint annotations, the description adds substantial behavioral context: it fans out across multiple sources, soft-fails on the patents sunset, reports sources_used/sources_failed, and distinguishes empty sections as real 'no data'. It also explains name resolution and private-company handling. 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 it is dense and front-loaded with usage examples and the key preference directive. Some schema details are repeated, yet given the tool's complexity, most sentences earn their 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 complex multi-source profile tool with no output schema, the description covers inputs, output fields, source behavior, edge cases, and failure semantics. An agent has enough information to call the tool correctly and interpret its 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%, so the baseline is 3, but the description adds meaningful detail beyond the schema: concrete examples (AAPL, 0000320193, Moderna), the fact that type values are interchangeable, and name-resolution behavior. This helps an agent form correct values.

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

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

The description states a specific verb ('profile') and resource ('US public company') and clearly distinguishes this tool from chaining single-source lookups. Example queries like 'Tell me about X' make the trigger immediately recognizable.

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

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

It explicitly says to ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested. It also explains accepted input shapes and the expected behavior for private companies, which helps an agent decide when to invoke it.

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

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

Annotations already declare 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?

Annotations provide safety hints, but the description goes far beyond them by disclosing fee modeling limitations, gross-vs-net spreads, compatibility code meanings, what happens to unclassified legs, null temporal_alignment semantics, and which fields can be non-empty even when matched_pairs > 0. This is exemplary behavioral disclosure.

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 and dense, but almost every sentence carries necessary caveats or behavioral details. It is front-loaded with purpose and modes, though the wall-of-text format and repeated emphasis on temporal_alignment_unknown could be structured more cleanly.

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 bears full responsibility for explaining return behavior—and it does: spread[], top_spreads_pp, per-entry flags, skipped categories, low_confidence_pairs, fees_note, temporal_alignment, and warning fields. Edge cases are covered thoroughly, making the tool safely callable by 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds meaningful mode semantics: topic shortcuts auto-fetch matches, explicit ticker/slug override the mapped side, and both modes run the same matcher. This goes beyond the schema without repeating it.

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

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

The description opens with a precise statement of function—cross-venue spread between Kalshi and Polymarket for the same resolving question—and explains the two input modes. It lacks an explicit verb like 'retrieve' or 'compute' and does not directly distinguish itself from sibling tools such as polymarket_arbitrage, but the domain and behavior are clearly conveyed.

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

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

The description gives clear context on when to use the tool (custom pairings vs pre-mapped topics) and explicit caveats: most pre-mapped topics return compatibility warnings, pre-mapped topics are not necessarily tradeable, and Kalshi fees are not modeled. It does not reference alternative sibling tools, so it falls short of fully explicit alternaive routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 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?

Beyond the readOnly/idempotent annotations, it discloses ambiguity behavior (returns figi_candidates instead of asserting), explicit unresolved identifiers, source labeling, graceful degradation when LEI/FIGI sources are unavailable, and internal cascading lookup behavior. This is far more than annotations provide and compensates for the missing output schema.

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

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

The description is dense and front-loaded with examples and the key directive, and nearly every clause adds value. It is longer than average because of nested parentheticals, but it remains organized enough that the length 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?

With no output schema and a high-complexity multi-source lookup, the description covers inputs, output behavior, ambiguity handling, unresolved identifiers, source provenance, and failure degradation. An agent has what it needs to invoke the tool 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?

Although the schema already covers both parameters, the description adds crucial semantics: exact accepted forms for ticker/CIK/ISIN/name, drug brand/generic examples, and a strong caveat to pass only the entity name for bonds because trailing security-class words match nothing. This materially helps an agent construct correct values.

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 user phrasings and states the tool's job: resolving a spoken NAME to canonical identifiers that other tools require. It calls out 'Use FIRST whenever you have a name but need an ID,' which positions it against the sibling tools and distinguishes it from consumers of those IDs.

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 trigger conditions ('Use FIRST whenever you have a name but need an ID') and enumerates supported entity types with rich examples, so an agent knows when this tool applies. It does not name alternative tools or describe when not to use it, so it lacks the full when/when-not clarity needed for a 5.

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

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

Annotations already declare readOnly/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.