Stat Lv

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

Annotations already declare read-only and idempotent behavior, lowering the bar. The description adds meaningful context: the default model is free, using Anthropic requires a personal API key and direct payment, and returns per-model structure. This goes beyond annotations without any contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, then covers defaults/costs, return format, and use cases. Every sentence adds value with no repetition or filler.

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

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

Despite having no output schema, the description spells out the per-model return fields (score, confidence, signals, raw_response) and combined view, providing sufficient details for an agent to interpret results. The use cases and model cost disclosures complete the picture for a moderate-complexity 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 a baseline of 3 applies. The description supplements this by explaining that omitting models defaults to free Workers AI and that `_apiKey` is passed straight through with direct billing implications, adding practical 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 employs a specific verb ('probe'), names the resource ('one or more LLMs'), and defines the output ('score visibility 0-100 per model'). It distinguishes itself from question-answering sibling tools like ask_pipeworx by focusing on multi-model visibility scoring rather than direct queries.

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

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

The description provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies model selection defaults versus BYO-key Anthropic. However, it does not explicitly mention when not to use it or name alternative tools for comparative scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds valuable behavioral context: it routes to 5,366 tools across 1,396 sources, returns structured answers with stable pipeworx:// citation URIs, and notes it 'works on every tier' with 'one fast call'. 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 well-structured: it front-loads the primary directive ('PREFER OVER WEB SEARCH'), then provides categories, examples, and escalation paths. While some enumeration of domains is redundant for an agent, every section serves a purpose, and the overall organization earns a strong score.

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

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

Despite lacking an output schema, the description is remarkably complete for a default entry-point tool. It covers purpose, usage triggers, examples, escalation to siblings, performance expectations, and citation behavior. No critical context is missing for an agent to correctly select and invoke this 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% (all six parameters have descriptions, though they are aliases for the same 'question' field). The description adds examples of question formatting but does not introduce new parameter semantics beyond what the schema already states; the baseline of 3 applies because the schema carries the heavy lifting.

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

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

The description defines 'ask_pipeworx' as the default entry point for factual questions about real-world data, using the specific verb 'ask' and the resource 'Pipeworx'. It explicitly distinguishes from siblings by saying 'PREFER OVER WEB SEARCH' and 'Step up only when needed' to ask_pipeworx_grounded or deep_research, making the tool's role clear.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the user asks "what is", "look up", "find", "get the latest", ...' and lists concrete examples. It also provides when-not-to-use guidance by pointing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, fulfilling the 'alternatives' requirement.

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

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

Annotations declare read-only, open-world, idempotent, and non-destructive. The description adds experimental context: 'candidate routing improvements', 'no candidate is active right now', and 'falls back to nothing — this IS a full working router, just the experimental edge.' This discloses instability and functionality beyond what annotations provide.

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

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

Three sentences, front-loaded with 'Beta version of ask_pipeworx', and each sentence contributes context: identity, current state, usage, and fallback. Some details like the specific retirement date are extra, but the description remains concise and well-structured.

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

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

The description explains the tool is a full working router, currently matching ask_pipeworx exactly, and provides usage guidance. It mentions 'same response shape' which is sufficient given no output schema. Overall, it is complete enough for an agent to decide when and how 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?

The schema has 6 parameters, all aliases for 'question', each with descriptions, giving 100% schema description coverage. The tool description only says 'same arguments' and does not add new parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,366 tools, and states it is functionally identical to the stable ask_pipeworx. This distinguishes it from sibling tools like ask_pipeworx_grounded and bet_research. Specific verb+resource: 'Ask Pipeworx Beta' routes questions to 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?

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router to decide what merges. This gives clear when-to-use guidance and implies ask_pipeworx as the stable alternative for normal use.

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

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

Annotations only indicate read-only/idempotent behavior. The description adds critical behavioral context: the tool returns evidence-based answers with verbatim quotes, explicit refusal reasons (not_in_source, no_tool_match, etc.), and a structured output. 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 dense and front-loaded with purpose, followed by usage and cost. It is slightly long but every sentence earns its place, covering routing, output shape, refusal reasons, and usage guidance without waste.

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

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

Despite no output schema, the description fully specifies the return format on success and failure, includes routing details, and gives use-case context. It is complete for a tool of this complexity, especially given the rich annotations.

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

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

All 6 parameters are aliases for 'question' and schema coverage is 100%. The description does not add parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource+scope. It distinguishes itself from ask_pipeworx by emphasizing extraction using only tool results and explicit refusal behavior, making it unique among siblings.

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

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

Explicit guidance is provided: use when answers will be quoted/cited/acted on, and prefer ask_pipeworx for casual lookups due to the extra LLM call. This directly addresses when to use vs alternatives, even naming the alternative tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral detail beyond annotations: low-confidence resolution short-circuiting, closed-market handling, wide-spread marking, cancellation-rule parsing, and news fallback behavior (_fallback_attempted). 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 capitalized section labels, examples, and clear separation of concerns. The opening sentence front-loads the core purpose. While dense, nearly every sentence adds operational detail (resolver contract, parent event, safety routes) that an agent cannot infer from schema alone. It could be trimmed but 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?

With no output schema, the description fully explains response shapes (result.market, result.analysis, result.evidence), resolver contract fields (market_match_confidence, alternatives, suggestions), parent_event extractor, news fallback fields, and status codes (low_confidence_match, market_closed_or_inactive). It also covers blocking mechanisms and resolution-rule risks, making it extremely complete for a complex research 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 mostly restates the market parameter's formats (slug, URL, question text) with examples, but adds no substantial semantics beyond the schema's own descriptions for depth or include_raw. The fan-out examples are behavioral, not parameter-specific.

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 first sentence states a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly describes the tool's scope (single bet research), shows example market formats, and differentiates from siblings like polymarket_arbitrage or deep_research by focusing on individual bet data synthesis.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', which gives clear usage context. However, it does not name specific alternative tools or provide explicit when-not-to-use guidance, though the classifier and fan-out examples imply suitability.

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, non-destructive), the description discloses rich behavioral details: it performs parallel lookups, pulls specific data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. This far exceeds annotation coverage, giving the agent a clear model of what happens.

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

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

The description is well-structured and front-loaded with trigger phrases, then elaborates on type-specific behavior and output. Every sentence adds value—there is no filler or repetition of annotations. It is appropriately sized for a tool with two modes and multiple data sources.

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

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

Given the tool's complexity (two entity types, multiple data points, sorting, citations) and the absence of an output schema, the description fully covers return values ('paired data + pipeworx:// citation URIs'), sorting behavior, and scope (2–5 entities). It is sufficiently 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%, so baseline is 3. The description adds meaning by explaining what each type parameter pulls ('type="company" pulls LATEST 10-K revenue...', 'type="drug" pulls FAERS...') and gives examples for values ('AAPL','MSFT' for companies; 'ozempic','mounjaro' for drugs). This enriches the schema without being redundant, though it does not add new syntax rules.

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 uses a specific verb (compare) and resource (entities), and distinguishes itself from siblings by noting it replaces sequential single-pack lookups and by listing trigger phrases.

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

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

Explicit usage triggers are given ('Compare X and Y', 'which is bigger', 'rank these companies'), along with a clear preference directive: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also separates behavior by type (company vs drug), providing concrete when-to-use context and implicitly naming the alternative (sequential single lookups).

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

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

The description goes far beyond the annotations by disclosing account/sign-in requirements, paid-tier depth, latency expectations (15-60s / ~90s), the findings packet format with evidence/confidence/source/fetched_at/citations, gaps[] for unanswered facets, contradictions[] for disagreement, and the semantic excerpting behavior. It also explicitly states it never invents findings. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

Although long, the description is front-loaded with the most critical constraint (ACCOUNT REQUIRED) and every sentence carries substantive guidance—usage boundaries, return structure, latency, limitations, and behavioral guarantees. The density is justified by the tool's complexity and the high stakes of correct invocation.

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

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

With no output schema, the description fully compensates by detailing the findings packet, gaps[], contradictions[], hop field, citation URIs, and excerpting approach. It also covers account/auth prerequisites, cost tiers, latency, and when to choose alternatives, making it complete 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 the baseline is 3, but the description adds meaningful parameter guidance: it clarifies that 'question' should accept broad/multi-part natural language ('decomposition is the point'), and explains deeper behavioral differences for depth values (standard's gap recovery, thorough's lead-chasing and contradiction pass) beyond the schema's own enum descriptions. This pushes it slightly above baseline.

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

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

The description opens with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources' and explains how the tool decomposes questions, routes to tools in parallel, and returns a findings packet. It clearly distinguishes deep_research from ask_pipeworx and other siblings by emphasizing this is NOT open-web search.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even 'If you are not signed in, use ask_pipeworx instead'. This is a model of clear tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral detail: it returns top-N tools with names, descriptions, and full input schemas, and says results are 'ready to call directly, no second schema lookup needed.' This goes beyond what annotations convey, though it doesn't describe pagination or error 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 longer than strictly necessary but each sentence adds value: purpose, usage context, return format, and a 'call first' heuristic. It is front-loaded with the core purpose and does not waste words, though the domain list is somewhat lengthy.

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/meta tool with no output schema, the description is self-sufficient: it explains what results look like (names, descriptions, full schemas), addresses why you would use it first, and lists the covered domains. Given the low complexity of parameters, this is complete enough for an agent to select and 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 the schema already documents query, limit, and all aliases (q, task, search, description). The description reinforces the query parameter's purpose but does not add meaning beyond the schema's own detailed parameter descriptions. Baseline 3 is appropriate since the schema carries the semantic load.

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

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

The description opens with a specific verb and resource: "Find tools by describing the data or task." It distinguishes this meta-tool from the many domain-specific siblings by clearly stating its role: browse/search/discover what tools exist for a broad list of domains. This is immediately clear and differentiates it from tools like query_table or validate_claim.

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

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

The description states when to use it: "Use when you need to browse, search, look up, or discover what tools exist" and gives an explicit sequencing directive: "Call this FIRST when you have many tools available and want to see the option set (not just one answer)." It does not name specific alternatives but implicitly contrasts with calling a single tool directly, and the sibling list provides the alternative set.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond that: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specifies return structure, and discloses the PatentsView API sunset with soft-fail behavior and GDELT→GNews fallback. 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?

Though lengthy, every section earns its place: example queries, usage directive, source list, return fields, and input constraints. It is organized and front-loaded with the most actionable information. The density is appropriate for a complex aggregation tool.

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

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

Given the tool's complexity and the lack of an output schema, the description thoroughly covers what the user gets: specific return fields, source breakdown, failure behavior, and input requirements. It also differentiates from sibling research tools like resolve_entity, making it contextually complete for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces parameter semantics with concrete examples ('AAPL', '0000320193') and reiterates that names are unsupported, pointing to resolve_entity. It adds practical clarity beyond the schema's existing descriptions, though it largely restates them with 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 it produces a 'full cross-source profile of a US public company in ONE parallel call' with example queries ('Tell me about X', 'research Acme'). It explicitly distinguishes from sibling tools by instructing to prefer it over chaining single-pack lookups for holistic views, and notes when to use resolve_entity for name-only inputs.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: names are not supported, instructing to use resolve_entity first. This allows the agent to select the tool appropriately among its siblings.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive, idempotent operation. The description adds that it clears 'sensitive data' and that the memory was 'previously stored,' but this is more about purpose than behavioral detail. It does not contradict the annotations, but it also does not significantly extend beyond them.

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

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

The description is exactly two sentences: the first states the core action, the second gives usage guidance and references related tools. Every word earns its place, with 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?

For a tool with one required parameter, a complete schema, and annotations covering destructiveness and idempotency, the description sufficiently explains purpose and usage. It does not mention error handling (e.g., what happens if the key doesn't exist), but that is arguably covered by the idempotentHint annotation and is not essential for this 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?

Schema coverage is 100%: the 'key' parameter is described as 'Memory key to delete.' The description's mention of 'by key' adds no new meaning beyond the schema, so it earns the baseline score for high coverage.

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

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

The description opens with 'Delete a previously stored memory by key,' which clearly specifies the action (delete) and the resource (memory by key). It also mentions pairings with 'remember' and 'recall,' which helps distinguish it from the sibling tools that store and retrieve memories.

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 scenarios ('when context is stale, the task is done, or you want to clear sensitive data'), and it names the related tools 'remember' and 'recall' for context. However, it lacks an explicit 'when not to use' statement, which prevents a perfect score.

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

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

The description adds behavioral context beyond annotations by outlining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also notes the output is a single text blob. This complements the readOnly/idempotent hints without repeating them or contradicting.

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 efficiently structured: a clear opening sentence, a process sentence, and a concise use-case list. No filler or redundant information; every sentence adds value.

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

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

For a tool with only 2 parameters and no output schema, the description provides a complete picture: what it does, how it works, what the output looks like, and when to use it. Annotations cover safety, so no additional behavioral disclaimers are needed.

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. The description adds only marginal meaning ('any URL' vs. schema's 'Full URL'), and does not elaborate on max_links. This matches the baseline of 3 for high schema coverage with minimal description contribution.

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 verb and resource: 'Generate a production-ready llms.txt file for any URL.' It specifies the exact output format (standard llms.txt markdown) and distinguishes this tool from sibling tools focused on visibility scanning by focusing on 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?

The description provides concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It lacks explicit 'when not to use' or named alternatives, but the use cases give clear guidance for when the tool is appropriate.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds the behavior that only the caller's subscriptions are returned and lists the exact fields in the response, which is useful beyond the annotations. 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 two sentences: the first states the action and return fields, the second provides usage guidance. It is front-loaded, concise, and every sentence adds value.

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

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

For a simple read-only tool with one optional parameter, the description fully covers the purpose, safe behavior (via annotations), return fields, and when to use it. The lack of an output schema is mitigated by listing the fields in the 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?

The sole parameter include_inactive is fully described in the schema (100% coverage), so the description does not need to elaborate. The description's mention of 'active subscriptions' aligns with the default behavior, but adds no extra semantics 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 lists the caller's active subscriptions, which is a specific verb and resource. It also enumerates the return fields, distinguishing it from sibling tools like subscribe and unsubscribe that mutate 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?

The description provides clear context on when to use the tool: 'before adding more' (pre-subscribe check) and 'to find an id to cancel' (pre-unsubscribe lookup). It does not explicitly name alternatives but strongly implies them through the use cases.

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

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

The description discloses several behavioral traits beyond the annotations: rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and the organizational effect ('The team reads digests daily and signal directly affects roadmap'). This provides meaningful context for the agent about consequences and constraints.

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

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

The description is concise and front-loaded with the core purpose. Every sentence earns its place: purpose, use cases, content guidelines, team behavior, and rate limit/quota information. No redundant or vague language.

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

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

For a simple feedback tool with three parameters and no output schema, the description fully covers purpose, usage, behavioral constraints, and parameter mapping to user scenarios. It is complete without over-explaining, and the schema handles the remaining structural 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 provides 100% coverage with detailed descriptions for all parameters, including the enum values for 'type' and the structure of 'context'. The description adds marginal value by linking type values to use cases ('bug' → wrong/stale data), but the schema carries the primary semantic weight, so the baseline of 3 is appropriate.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It unambiguously describes the tool's purpose and inherently distinguishes it from the sibling research and data tools, none of which provide feedback functionality.

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

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

The description explicitly states when to use the tool: 'Use when 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 clear directive on what not to do ('don't paste the end-user's prompt'), making usage boundaries unmistakable.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the description adds valuable context beyond them: it discloses the data source ('CF analytics-engine'), privacy guarantee ('no PII'), return shape ('(pack, tool, count)'), and caching behavior ('Cached 5min-1h depending on window'). This enriches the behavioral model without contradicting annotations.

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

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

The description is three sentences and each earns its place: a purpose statement, numbered use cases, and a data/caching note. It's slightly redundant with the schema's window description, but the structure is clear and front-loaded with the most important 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?

With only one optional parameter, rich annotations, and no output schema, the description sufficiently covers return contents, use cases, data source, privacy, and caching. It could specify exact response formatting, but the minimal shape ('(pack, tool, count)') is enough for an agent to understand what to expect.

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

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

The schema covers 100% of parameters and already explains the window enum's tradeoff between 'hot right now' and 'steady-state demand,' so the description adds little parameter-level meaning beyond restating the options. It does mention the cache window dependence, but that's a behavioral nuance rather than parameter 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 clear, specific purpose: 'What other AI agents are calling on Pipeworx right now' and enumerates the exact deliverables: 'top tools, top packs, and total call volume.' It differentiates from siblings like discover_tools by emphasizing aggregate trending behavior over a window rather than general discovery.

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, numbered use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with other agents' needs. It gives clear context for when to use the tool, though it does not explicitly state when not to use it or name 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?

The description elaborates on thresholds (3pp), semantic anchor, partition filter, fill check, and response structure, adding substantial detail beyond the readOnly/idempotent annotations. It even warns not to trade when realizable edge ≤ 0, a key behavioral caveat.

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 uses labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. While every sentence carries information, it is more verbose than strictly necessary, with some repetition in the event/topic paragraphs.

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 multi-mode tool with no output schema, the description covers all modes, response fields, fill-check behavior, and related tool usage. It leaves no obvious gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, but the description enriches both params with concrete examples (fed-decision-may-2026, Strait of Hormuz) and explains behavioral differences (walks child markets vs searches related events). This adds value beyond the schema's already decent 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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with these specific checks.

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

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

It provides explicit usage modes: no args for trending_scan, event vs topic, with recommended use cases. It also names an alternative tool for custom sizing (polymarket_fill_risk), satisfying the when-to-use vs alternatives criterion.

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 substantial behavioral context: caching at KV level for 1h keyed on all knobs, details on model families and their computation (e.g., lognormal barrier from 90d FRED log-returns), diagnostic fields enabling callers to see why segments are empty, and the 24h-move warning when the edge is already priced in. 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 densely structured with clear sections (model families, response top-level, tradeable-edge knobs, diagnostics). It front-loads the one-sentence summary before diving into technical details. Every sentence adds value, though the length is significant; for a tool with 9 parameters and multiple response segments, this is acceptable and not wasteful.

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

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

Given 9 optional parameters and no output schema, the description fully compensates by detailing response structure (by_segment, fed_candidates/fed_note, _diagnostics), including why fed bets are excluded from ranking, and covering edge cases like placeholder-slug filtering and partition overround bias correction. It provides all necessary context 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?

The input schema already has 100% coverage with rich parameter descriptions. The description goes further by explaining cross-parameter interactions, such as how min_partition_leg_kelly applies to best per-leg Kelly inside top_legs (since parent-level kelly_fraction_half is always 0 for partition arbs), and by contextualizing slippage_pp defaults with market reality (Polymarket zero fees but 20-50bp spreads). This adds 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 opens with a specific, actionable purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It goes on to enumerate distinct model families and response segments, clearly differentiating this from generic market scanning tools and from sibling tools like polymarket_arbitrage by focusing on edge discovery driven by Pipeworx data.

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

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

The description explicitly frames the primary use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the purpose of each knob (e.g., min_liquidity, max_spread_pp) and provides guidance on when to adjust them (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). It does not explicitly name alternative tools for exclusion, but the context is clear enough.

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

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

Annotations already declare read-only/non-destructive, so description adds substantial behavioral detail: snapshot generation on cache-miss implies gaps, 60-day TTL bound, daily-close basis of decay, and expired opportunity semantics. This exceeds annotation value and informs interpretation.

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?

Well-structured with labeled Args/Response/Limits sections, front-loading the core question. Although it is lengthy, every section adds necessary interpretive information and the density is justified.

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

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

No output schema exists, but the description fully specifies response fields (tracked, expired, snapshot_dates), their subfields, and interpretation caveats. It also covers data availability limitations, making it sufficiently complete for a read-only telemetry 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 covers both parameters with defaults, clamp ranges, and enum values, so baseline is 3. Description adds the notion of lookback history and snapshot family context, but mostly restates schema details.

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

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

Clearly defines tool as edge persistence/decay telemetry from daily polymarket_edges snapshots, distinguishing it from sibling polymarket_edges by focusing on time-series, first_seen, trend, and decay. The specific question it answers makes its scope unmistakable.

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

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

States the exact analytical question and contextualizes why old wide edges matter differently, giving implicit guidance on when to use. However, it does not explicitly name sibling alternatives or state when not to use, so it stops short of full exclusion guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the tool's internal behavior: it 'walks the ladder', computes top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and returns a verdict. It also warns about partial basket fills converting arb into unhedged directional positions. This adds significant context not available in structured metadata, with no contradictions.

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

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

Though long, the description is information-dense and front-loaded with a clear purpose. It is structured around SINGLE-MARKET and BASKET modes, and every sentence contributes necessary operational detail. For a tool of this complexity with no output schema, this length is justified and well-organized.

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

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

The tool has no output schema, so the description compensates by enumerating all key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, realizable_sum, capture_ratio, thin_legs[], etc.). It also covers parameter interpretation, defaults, and usage context, making it complete enough for an agent 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%, but the description dramatically enhances parameter understanding. It explains that size_usd is 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional... shares per leg' in basket mode. It also clarifies side defaults and basket auto-detection. This goes well beyond the schema's field descriptions and is essential for correct invocation.

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

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

The description opens with a precise, verb-driven purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two operating modes (single-market and basket), and explicitly positions itself relative to sibling tools (polymarket_arbitrage, polymarket_edges) as the pre-trade risk check. This makes the tool's function unmistakable and distinct from its siblings.

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

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

The description gives explicit usage instructions: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the reasoning (theoretical overround on thin books is not capturable, partial fills create directional risk) and also differentiates when to use single-market vs basket modes. This is exemplary guidance for an agent.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals detailed behavioral nuances: compatibility warnings, temporal alignment checks, skipped_cross_type/subtype counters, and the meaning of aligned:false. It discloses limitations ('pre-mapped ≠ tradeable') and explains under what conditions spreads are 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 long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). However, it is somewhat verbose, repeating warnings about pre-mapped topics not being tradeable. It earns its place for a complex tool, though a tighter edit would improve conciseness.

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

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

With no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spread[], top_spreads_pp), safety fields, and temporal alignment. It covers edge cases and failure modes, making it complete for the tool's complexity.

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

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

Although schema covers all parameters, the description adds substantial semantics: it explains the 'topic' shortcuts are pre-mapped, how 'kalshi_event_ticker' and 'polymarket_event_slug' override the mapped sides, and how the two modes interact. This goes far beyond bare parameter names.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with specific verbs ('cross-venue spread', 'auto-fetch') and distinguishes itself from siblings by focusing on two venues. It also explains the two modes, making its scope unambiguous.

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

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

The description provides concrete usage instructions via TWO MODES (topic shortcuts vs explicit tickers) and includes a caution that pre-mapped topics often return compatibility warnings, indicating when not to trust results. However, it does not explicitly name alternative tools (e.g., polymarket_arbitrage) for when this tool is not appropriate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a specific behavioral constraint: the path must be provided without a '.px' suffix, which is not evident from the schema. It also identifies the body format as a PxWeb query object. These details go beyond the annotations and help avoid common usage errors.

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 primary purpose, and includes essential usage details without any filler. Every sentence adds value, making it highly concise and well-structured.

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

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

Given the tool's moderate complexity, the provided annotations, and rich schema descriptions (including an example of the body structure), the description is largely complete. It covers the key operational detail (path format) and the body type, though it does not describe the response format, which is acceptable since there is no output schema and annotations indicate a safe read-only 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 schema descriptions already cover 100% of parameters, providing examples for both path and body, so the baseline is 3. The description adds meaning by clarifying that 'body' is a PxWeb query object and by specifying the path format constraint (no '.px' suffix), which is not present in the schema. This adds practical value for correct invocation.

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

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

The description starts with 'Pull data from a table,' which is a specific verb+resource and clearly indicates the tool's function. It does not explicitly differentiate from sibling tools like table_meta, but the purpose is unambiguous. The mention of 'PxWeb query object' adds useful context about the query mechanism.

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?

There is no explicit guidance on when to use this tool versus alternatives, such as table_meta for metadata. However, it provides usage instructions for the path parameter ('Use the bare table path with no ".px" suffix') and indicates the body must be a PxWeb query object, which implies it is for data retrieval. This is implied usage context rather than explicit selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description is not required to repeat them. It adds useful context beyond annotations: scoping to your identifier (anonymous IP, BYO key hash, or account ID) and the behavior of omitting the key to list all saved keys. This is valuable behavioral transparency.

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

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

The description is three sentences long. Every sentence earns its place: the first defines the core action and the optional behavior, the second provides motivation and examples, the third covers scoping and sibling tools. It is front-loaded with 'Retrieve a value' 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?

Given the tool's simplicity (1 optional parameter, no output schema) and strong annotations (readOnlyHint=true, idempotentHint=true), the description is complete. It explains the return behavior (value or list of keys), the scope, and the intended use case, making it 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?

Schema coverage is 100%, and the schema already describes the 'key' parameter with 'omit to list all keys'. The description reinforces this and adds illustrative examples (user's target ticker, address, prior research notes) that help the agent understand what kinds of values are stored. The baseline is 3, and the examples push it to 4.

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

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

The description uses a specific verb+resource: 'Retrieve a value previously saved via remember' and also covers the list-all variant. It clearly distinguishes from siblings: 'Pair with remember to save, forget to delete.' Examples of use cases further clarify the purpose.

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

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

The description explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names related tools (remember and forget) but does not explicitly say when NOT to use it or describe an alternative for the same task. It implies the workflow clearly, so it earns a 4.

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?

Description explicitly discloses the mark_read:true side effect of flagging events read, which changes future results. However, this contradicts the readOnlyHint:true annotation, since flagging read is a persistent state mutation. Per rubric, a contradiction yields score 1 and is flagged.

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?

Five concise sentences, front-loaded with purpose, each providing useful context: payload fields, filters, mark_read side effect, polling, and REST mirror. No fluff or unnecessary repetition of schema definitions.

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

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

Description covers return payload fields, filtering, mark_read behavior, polling, and an external URL, which is strong for a read/list tool with no output schema. Remaining parameters (limit, unread_only) are documented in the schema, so no major gaps; only the annotation contradiction prevents 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?

Schema covers all 5 parameters (100% coverage), so baseline is 3. Description adds value with an example filter type ('sec_8k'), explains mark_read semantics (next call shows only newer events), and clarifies since expects an ISO timestamp.

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 'Pull fired events from your subscription feed,' a specific verb+resource that clearly states what the tool does. It also details the alert payload fields and filter options, distinguishing it from siblings like recent_changes and 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?

The description provides clear usage context: filtering by type (e.g., 'sec_8k') and since, mark_read behavior, and polling suitability. It even points to an alternative REST endpoint for scripts/dashboards, but doesn't explicitly name sibling tools or state when not to use it.

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

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

The description richly discloses behavior beyond the annotations: it fans out in parallel to multiple APIs, explains the GDELT-preferred/GNews-on-failure logic, notes USPTO's soft-fail due to PatentsView API sunset, and describes the return structure (changes[], total_changes, citation URIs). 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 dense yet efficient: front-loaded with recognizable user phrases, then a compact core statement, source list, parameter notes, return summary, and alternative tool pointer. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's complexity (three data sources, fallback logic, soft-fails) and absence of an output schema, the description covers all essentials: what it returns, how `since` works, source-specific caveats, and when to choose an alternative. It is fully self-contained.

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

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

Schema coverage is 100%, so the baseline is 3. The description echoes the schema's parameter meanings (e.g., `since` formats) and adds a typical-use suggestion ('30d' or '1m') and examples of `value` (ticker or CIK). This is helpful but does not substantially extend beyond what the schema already documents.

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 triggers, then clearly states it returns a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts itself with entity_profile, making the purpose unmistakable and well-differentiated from siblings.

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

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

The description provides explicit usage guidance: use it for 'what's new' / 'latest on Y' style queries, and directly names an alternative ('Use entity_profile instead when you want the static profile... regardless of window'). It also explains the GDELT→GNews fallback behavior, giving clear context for when this tool is appropriate.

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

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

The description adds valuable behavioral context beyond annotations: memory is 'scoped by your identifier,' authenticated users get persistent memory, anonymous sessions retain for 24 hours. This complements the idempotentHint and destructiveHint annotations without contradicting them.

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

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

The description is concise yet information-dense, with three sentences that front-load the purpose and follow with usage, persistence, and pairing. Every sentence serves a distinct function with no redundancy.

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

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

For a simple 2-parameter write tool with rich annotations and full schema coverage, the description completely covers when to use, how data is stored, and how it relates to sibling tools. No output schema is needed for a store operation, so its absence is not a gap.

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

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

Schema description coverage is 100% with detailed descriptions for both 'key' and 'value.' The description does not add parameter-specific semantics beyond the schema, but it does reinforce the key-value nature and gives examples in context. 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: 'Save data the agent will need to reuse later.' The verb 'save' plus resource (key-value memory) is specific, and it distinguishes itself from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete.'

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

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

Explicit usage guidance is provided: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also mentions persistence differences for authenticated vs anonymous users, and names companion tools (recall, forget) for related operations.

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 readOnlyHint and idempotent, and the description adds concrete behavioral details: it returns specific fields (ticker, CIK, company_name; RxCUI, ingredient, brand), cites source URIs, auto-disambiguates names, and cascades through multiple endpoints. This explains what actually happens without contradicting the read-only nature.

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 compact paragraph that front-loads example queries and then organizes supported types with clear bullets. Every sentence contributes distinct information—no filler or repetition of schema. It is well-structured and appropriately sized for the tool's complexity.

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

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

Without an output schema, the description fully specifies return values for both entity types, including source URIs. It also explains the internal cascade behavior, covering the practical aspects an agent needs to invoke and interpret the tool. This is complete for a lookup 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% and both params are described, but the description adds real-world examples like 'AAPL', '0000320193', 'ozempic', and 'metformin', clarifying accepted formats. It also explains the effect of 'type' on output and how ambiguous values are auto-disambiguated, which exceeds the schema descriptions.

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

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

The description opens with natural-language examples ('What's the ticker for…' / 'find the CIK for…') that immediately clarify the tool's function: resolving a spoken entity name to a canonical identifier. It explicitly contrasts with siblings by saying 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from lookup tools like query_table or 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?

Explicit usage guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It details the two entity types (company and drug) and their accepted inputs, and notes the tool replaces 2-3 manual lookups, signaling when it's efficient. This covers both when and why to use it.

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

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

Annotations already cover read-only/idempotent/destructive safety. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond what annotations provide.

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

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

Three sentences, each earning its place: main action, internal process, use case + output. Front-loaded with the core purpose and 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?

With no output schema, the description compensates by specifying the return structure (ranked list with score, confidence, signal density). It also covers the intended use case ('does Claude know about us as well as our competitors?'), making the tool's behavior and output clearly understandable.

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 some context around the entities parameter ('your brand + N competitors') but this is also largely captured in the schema's 'First entry treated as the subject' note. No significant new parameter meaning is added.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It explicitly distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison and ranking, making the tool's purpose unmistakable.

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

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

Provides clear context ('competitive AI-marketing audits') and a concrete example question. It implies this tool is for multi-entity comparisons but does not explicitly state alternatives for single-entity checks or when not to use it, so it stops short of a 5.

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

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

Annotations already mark the operation as read-only and idempotent; the description adds behavioral details such as fan-out to external services, performance expectations (5-30s first measurement), and graceful partial failure with sources_failed. It also enumerates all returned fields, which is crucial given no 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 but uses a logical flow: core purpose, usage triggers, return summary, ecosystem limitation, and failure behavior. There is no fluff; every sentence adds operational value and front-loads the primary purpose.

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

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

Given the lack of an output schema, the tool description fully enumerates the return block fields and mentions the alternative versions list and per-advisory detail. It also covers timeout behavior and ecosystem boundaries, making it complete for a complex composite 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 has 100% description coverage for both package and version, including defaults. The description does not add parameter-specific information beyond what the schema provides, so the baseline 3 applies because the schema carries the full burden.

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 is a composite npm package evaluation check, combining deps.dev and bundlephobia data, and specifies it returns summary metrics and advisories. This distinguishes it from siblings by the composite nature and npm ecosystem scope.

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

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

It explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and notes the NPM-only limitation, directing other ecosystems to deps.dev:version directly. This provides clear if-then guidance and names an alternative for non-NPM cases.

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

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

Beyond the read-only/idempotent annotations, the description discloses algorithmic details (BGE-base-en embeddings, cosine, 500-char windows), a hard limit (200K chars with truncation and flagging), and return format (offsets and similarity scores). 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?

Four tightly packed sentences cover core function, usage scenario, pairing, and technical constraints. There is no redundancy; every sentence earns its place and the main action 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 carefully explains the return value (passages with offsets and similarity scores), operational boundaries (200K cap, truncation flag), and algorithm details. This makes the tool self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the input schema already fully describes all three parameters. The description reinforces 'text' as content from a previous fetch and gives example queries, but it does not introduce significant new semantics 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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by explicitly positioning it against 'ask_pipeworx_grounded' and framing it as a component of a fetch-then-search workflow.

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 an explicit when-to-use condition ('when the record is too big to cram into the prompt') and names a direct alternative/complement ('Pairs with ask_pipeworx_grounded'). This provides clear context and a practical workflow suggestion.

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

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

Annotations already declare read-only and safe operation. The description adds meaningful behavioral context by explaining the tree structure and the distinction between folder ('l') and table ('t') entries, which helps the agent interpret results.

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 main action, and contains no wasted 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 simple one-parameter navigation tool, the description covers the core behavior including entry types and root behavior. It could mention response shape or error cases, but it is sufficient given the annotations and simple schema.

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

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

The input schema provides full coverage for the 'path' parameter with a clear description and examples. The tool description reiterates path behavior but adds little beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description clearly states 'Navigate the subject tree' with a specific verb and resource. It explains root and sub-path behavior, distinguishing it from query/table tools, though it does not explicitly name 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?

The description provides how-to details (empty path lists folders, types 'l' and 't') but does not explicitly state when to use this tool versus alternatives like query_table or table_meta. Usage is implied for exploring the subject tree.

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

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

The description goes well beyond the annotations by disclosing the auth requirement, supported subscription types, phone verification, the 10/day SMS cap, webhook HMAC signing details, the one-time delivery.webhook_secret return, and auto-disable after 10 consecutive failing runs. There is no direct contradiction with the idempotentHint annotation; the text doesn't explicitly promise non-idempotent 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 dense but efficient; every sentence contributes substantive detail. It front-loads the purpose and return value. The structure could be improved by separating types and delivery channels into clearer segments, but the prose remains readable 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?

Given the tool's complexity and the absence of an output schema, the description covers auth requirements, all major subscription semantics, delivery channels, security details, and limits. It does not fully describe the complete response shape beyond the subscription id, and it omits two enum types in the prose, but the schema fills those gaps. Overall, it is sufficiently complete for a well-documented API.

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 context with concrete examples for each subscription type and delivery behavior (e.g., feed always on, email/SMS/webhook). It omits patent_grant and clinical_trial from the top-level "Supported types" list even though the schema includes them, which is a minor inconsistency.

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

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

The description uses a specific verb and resource: "Create a proactive monitoring subscription to a live-data event stream," and immediately states the return value ("Returns the new subscription id"). This clearly distinguishes it from sibling tools like recent_alerts, list_subscriptions, and unsubscribe by positioning it as the creation point for persistent monitoring.

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 usage context: it requires a Pipeworx OAuth account, notes that anonymous and BYO cannot persist subscriptions, and explicitly mentions the always-on feed as an alternative pull mechanism via recent_alerts. It does not exhaustively enumerate when not to use the tool relative to every sibling, but it provides enough directional guidance.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, so safety is covered. The description adds behavioral context by describing the return format (category-bucketed example questions with tool+argument shape, from live catalog) and the topic-filtering behavior. It does not describe output limits or auth requirements, but these are less relevant for a read-only onboarding tool.

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

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

The description is somewhat long but front-loaded with user intents and has a clear dash-separated structure. Each clause adds value: purpose, return format, parameters, and usage timing. No waste, but 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 simplicity (1 optional param), rich annotations, and the description covering purpose, return value, usage, and when to use, it is fully complete. The mention of learning meta-tools provides additional onboarding context. No output schema means no need to explain return values beyond what's stated.

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

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

Schema already describes the topic parameter and values, so baseline is 3. The description adds concrete usage examples ('finance', 'pharma', 'betting') and clarifies the default behavior ('full spread') vs focused, moving it above baseline.

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

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

The description uses a specific verb ('returns category-bucketed example questions') and identifies the resource (Pipeworx capabilities) and the deliverable (each with exact tool + argument shape). It clearly distinguishes itself from sibling meta-tools like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point.

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 instructs 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. It also gives invocation guidance (no args vs topic) and names alternatives, satisfying the when-to-use vs alternatives requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds a useful input constraint (bare table path with no '.px' suffix), but does not disclose additional behavioral details such as return format or potential errors. This modest addition warrants a mid-range score.

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, with two short sentences front-loading the core purpose and then a specific usage guideline. Every word serves a purpose.

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

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

For a simple read-only tool with one parameter and no output schema, the description sufficiently covers the purpose and input requirement. It doesn't explain the structure of the returned definition, but the basic information is adequate. A bit more detail on the expected response could improve 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?

The schema has 100% coverage for the single 'path' parameter, but the description adds crucial semantic information by specifying that the path must be used without the '.px' suffix. This goes beyond the schema's example, improving the agent's ability to invoke the tool correctly.

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 returning table definition metadata, specifying 'dimensions, valid values'. While it lacks an explicit verb like 'get' or 'retrieve', the noun phrase is unambiguous and distinguishes it from data-querying siblings like query_table. The path usage hint adds 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 clear context: use this tool to obtain table definitions, dimensions, and valid values. It also provides a specific path format instruction (no '.px' suffix). However, it does not explicitly name alternatives or state when not to use the tool, though the sibling list suggests query_table handles data queries.

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

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

The description goes beyond the annotations (which already indicate non-read-only, non-destructive) by explicitly stating ownership enforcement and the deactivation mechanism. It also explains that historical events remain available via recent_alerts, adding valuable behavioral context not present in the annotations.

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

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

Two information-dense sentences with no filler. Each clause earns its place: action, ownership, deactivation, and historical availability.

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 simple tool (1 param, good annotations, no output schema), the description covers the action, constraint, and post-condition. It does not need to explain return values since the outcome is clearly described and the tool is straightforward.

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 id parameter is already well documented with 'Subscription id (uuid) returned by subscribe.' The description only says 'by id' and adds no additional parameter-level meaning, so baseline 3 applies.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription by id', clearly distinguishing it from siblings like list_subscriptions. It also adds scope (ownership enforcement) and outcome (deactivation not deletion), making the purpose unambiguous.

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

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

The description provides clear context: it states the ownership constraint and explains that the row is deactivated, not deleted, which implies use for canceling while preserving history. However, it does not explicitly mention alternative tools (e.g., subscribe, list_subscriptions) or say when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive hints. The description adds substantial behavioral context: the dual-path pipeline (SEC EDGAR/XBRL vs. grounded fallback), the use of verbatim evidence, exact percent-delta math, and the set of possible verdicts. It also discloses that results include citations and reasoning, going well beyond the structured 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 (about five sentences) but each sentence adds valuable context: trigger phrases, usage guidance, routing logic, return format, and efficiency benefit. It is front-loaded with the core purpose and immediately usable examples. No fluff, though slightly more verbose than strictly necessary.

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

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

Given the tool has no output schema, the description thoroughly explains what is returned (verdict types, actual value, citation, reasoning). It also covers input examples, tolerance semantics, routing behavior, and claims to replace multiple sequential calls. This is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining how tolerance_pct affects verdicts via 'exact percent-delta math' and how the claim's wording implies a default tolerance. It also provides natural-language framing for the claim parameter, complementing the schema examples with the tool's verification purpose.

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 names the tool's function: natural-language claim verification with a specific verb ('verify', 'validate') and resource ('claim'). It includes numerous trigger phrases and distinguishes itself from general research tools by stating it returns a verdict with evidence. The scope (company-financial vs other claims) further sharpens its identity.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear context. It also explains the routing for company-financial claims vs. other claims and notes that it replaces 4-6 sequential calls. However, it does not name alternative sibling tools or state explicit when-not-to-use conditions, so it stops short of full 5.

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