Oregon Open Data

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context: default free Workers AI model, BYO Anthropic key with direct billing, and passthrough to api.anthropic.com. No contradiction with annotations.

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

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

The description is four sentences, front-loaded with the core functionality, and every sentence adds concrete detail. There is no redundant phrasing 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?

Even without an output schema, the description specifies the per-model return shape ({score, confidence, signals, raw_response}) and the combined view. It covers defaults, optional parameters, use cases, and cost implications, making it complete for this 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the default model, the cost implication of providing _apiKey, and how the context parameter helps disambiguate entities.

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 ('Probe') and clearly defines the resource scope (business/brand/product/topic) and measurable outcome (visibility score 0-100 per model). It distinguishes itself from similar sibling tools by covering any entity type and providing per-model breakdowns.

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 use cases are provided: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not name alternative tools or state when not to use it, but the context is clear enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds useful behavioral context: it routes to one of 5,529 tools, fills arguments, returns structured answers with citation URIs, works on every tier, and handles live news. This goes beyond 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 long but well-structured: it leads with the strongest usage directive, then explains functionality, provides examples, and contrasts with alternatives. Every sentence adds value, though it could be slightly tighter.

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

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

For a complex tool with no output schema, the description fully covers purpose, usage, output format ('structured answer with stable pipeworx:// citation URIs'), and comparison to siblings. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% and the schema already documents the 'question' parameter with aliases. The description adds example questions but no new parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to authoritative structured data sources. It uses specific verbs ('routes', 'returns', 'fills arguments') and explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' for a wide range of topics, 'START HERE for most questions', and 'Step up only when needed' with specific alternatives for grounded answers or deep research. Also gives concrete examples of 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the experimental nature, the live candidate testing mechanism, the current inactive state, and the fact that it falls back to nothing—it's a fully working router. This adds rich behavioral context about potential future divergence and the comparison process, which annotations cannot convey.

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

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

The description is well-structured with front-loaded purpose, followed by current state, usage guidance, and a clarifying note. Every sentence adds value, and the length is justified given the experimental nature. 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?

Despite having no output schema, the description fully covers context: it identifies the tool as a beta router, explains the relationship to ask_pipeworx, clarifies the current identical behavior, and assures the user it's a complete working tool. This is complete for an agent to understand when and how to use 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 already provides 100% coverage, documenting all six properties as aliases for 'question'. The description only says 'same arguments' without adding parameter-specific details, so the baseline of 3 is appropriate since the schema carries the full 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 clearly states this is a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It explicitly differentiates from the stable ask_pipeworx by its experimental nature and current matching behavior, making its 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?

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It also clarifies that no candidate is active right now, so current behavior matches ask_pipeworx exactly, giving clear when-to-use context and implicitly contrasting with the stable sibling.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the extra LLM call cost, the exact return structure including evidence and refusal_reason, and the five specific refusal reasons. It also explains that the answer will be extracted using ONLY what the tool result contains, which aligns with the readOnlyHint and adds significant behavioral context.

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

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

The description is front-loaded with the core purpose ('Hallucination-resistant answer mode for high-stakes reads') and then logically covers mechanics, return structure, use cases, and cost. Every sentence earns its place; there is no filler or redundancy.

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

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

Given the tool's complexity (refusal modes, evidence extraction, cost implications), the description is remarkably complete. It covers behavior, return values, usage guidance, and alternatives. Since there is no output schema, the description compensates by fully specifying the return shape and refusal reasons.

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 documents all 6 parameters with clear descriptions (100% coverage), all as aliases for the question. The description adds no additional parameter-specific semantics, so the baseline score of 3 applies without needing compensation.

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 core function: a hallucination-resistant answer mode for high-stakes reads that extracts answers only from the tool result. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior, with a specific verb+resource structure.

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 tells when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides an alternative and cost tradeoff: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context beyond that: low-confidence resolution short-circuiting, closed-market status handling, wide-spread tradeability flags, news fallback fields, and the cancellation-rule risk analysis. This is exactly the kind of behavioral detail that annotations cannot convey.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the main purpose, and each section earns its place by covering important edge cases. However, it is quite dense and could potentially overwhelm an agent, so not a 5.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so thoroughly: result.market fields, result.analysis fields, evidence keying, the resolver contract (match confidence, alternatives, suggestions), parent_event structure, news fallback semantics, and safety statuses. This is complete enough for an agent to correctly interpret outputs and avoid acting on low-confidence matches.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing concrete fan-out examples (BTC bet → coingecko + fred + gdelt; Fed bet → fred + kalshi_macro, etc.), which enriches the meaning of the 'market' and 'depth' parameters beyond the schema's brief descriptions. It also clarifies the impact of include_raw on response size.

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

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

The description opens with a specific verb+resource+scope: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It clearly distinguishes itself from sibling tools like polymarket_edges or deep_research by focusing on market-data fan-out and evidence packaging, and directly states the input forms (slug, URL, question text).

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 lists when to use the tool: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It gives clear context but does not name alternatives or say when not to use it, which would make it 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 read-only, open-world, idempotent, and non-destructive behavior, but the description adds substantial context: SEC EDGAR/XBRL and FAERS data sources, off-calendar fiscal-year handling, sort order by primary metric, and citation URIs. 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 a single dense paragraph but front-loaded with trigger phrases and imperative guidance. Every sentence contributes useful selection or behavioral detail, though a slightly more structured layout would improve scanability.

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

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

With no output schema, the description adequately explains return semantics: paired data, citation URIs, and sorting. It covers use cases, input constraints, data sources, and type-specific behavior, making it complete enough for reliable tool selection and invocation.

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

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

The input schema already documents both parameters with examples, giving a baseline of 3. The description enriches semantics by explaining what each type retrieves (latest 10-K metrics vs FAERS counts) and emphasizing the 2–5 range, which adds value beyond the schema.

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

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

The description opens with concrete trigger phrases and explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one call, distinguishing it from single-entity tools. The verb+resource is specific and 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?

It explicitly tells when to use the tool by listing comparative query patterns and provides an imperative 'ALWAYS PREFER over sequential single-pack lookups' directive. It also identifies the alternative (sequential lookups) and gives type-specific guidance for company vs drug.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by disclosing the exact return fields and the relationship to subsequent tools (resource_id needed for query/metadata). It does not repeat annotation info or contradict it.

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

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

The description is a single well-structured sentence that front-loads the action and resource, then lists return fields and provides a clear next-step instruction. Every clause earns its place 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 rich schema (100% parameter coverage) and annotations, the description is complete enough: it explains the tool's purpose, return fields, and how to proceed. It lacks only minor details like total count or pagination behavior, but these are not critical for a simple search tool with offset/limit in the schema.

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

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

Schema coverage is 100%, so the schema fully documents query, limit, and offset. The description adds no additional parameter semantics beyond what the schema already provides. It mentions 'keyword search' but that is already in the query parameter description. Thus, baseline 3 is appropriate.

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

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

The description clearly uses a specific verb ('Search') and resource ('Oregon Open Data catalog'), and specifies the return fields (resource_id, name, description, category, update date). It also distinguishes itself from sibling tools like metadata/query by instructing the user to pass the resource_id to those tools, making its role as the discovery step explicit.

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

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

The description provides clear context: it is for keyword searching of datasets. It implicitly differentiates from alternatives by telling the agent to pass the resource_id to query/metadata, implying this tool is the correct starting point. However, it does not explicitly state when not to use it or name alternatives beyond the passing instruction.

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

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

Beyond annotations (readOnly/openWorld/idempotent), the description discloses critical behaviors: requires an account (free/paid), decomposes questions and routes to 5,529 tools in parallel, returns findings with evidence/confidence/gaps[], explicitly 'never invented' answers, includes contradictions[] for standard/thorough, semantically excerpts large records, and gives latency expectations. This is rich, non-redundant context.

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

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

Though long, the description is front-loaded with the account requirement and then compactly covers what the tool does, when to use it, what it returns, and key caveats. Every sentence earns its place—no fluff or repetition. The logical flow (purpose → alternatives → behavior → depth details → output) makes it easy to parse.

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

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

With no output schema, the description fully explains return values: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation', gaps[], contradictions[], hop field, and citation_uri. It also covers edge cases (empty gaps for off-catalog topics) and performance expectations. For a tool of this complexity, the description is exceptionally complete.

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

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

Schema description coverage is 100%; both `question` and `depth` are fully explained in the input schema. The description adds some context (e.g., depth:"thorough" requires a paid plan, broad/multi-part questions are fine) but mostly reiterates the schema. This meets the baseline for high coverage without significant added 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 clearly states the verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It distinguishes from siblings by explicitly saying it is NOT open-web search and pointing to ask_pipeworx for single lookups. Even mentions the parallel tool routing, making what it does unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS / "what's the world saying about X" topics, prefer ask_pipeworx'. Also explains depth-level choices, ensuring the agent selects appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral detail: results include names, descriptions, and full input schemas with curated examples, and are 'ready to call directly, no second schema lookup needed' – this saves the agent an extra step. This goes beyond the annotations and is useful for predicting tool 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?

Four sentences, each earning its place: purpose, domain scope, return format, and usage timing. No filler or redundancy. The information is front-loaded with the core verb-phrase in the first sentence.

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 return values: tool names, descriptions, full input schemas with examples, and direct readiness to call. It also covers domain scope and explicit usage timing. For a discovery tool, this is complete.

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

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

Schema coverage is 100%, with all parameters having descriptions, including aliases (q, task, search, description) and limit semantics. The description adds no parameter-specific meaning beyond what the schema already provides; the 'top-N' notion is captured in the limit parameter's schema description. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists concrete domains (SEC filings, financials, FDA drugs, etc.) and distinguishes it from likely siblings like query or search_within by positioning it as a discovery/metadata tool for browsing the available tool set.

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 when you need to browse, search, look up, or discover what tools exist' and adds 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides both when-to-use and a when-not-to-use hint, without naming specific alternatives but giving clear context.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral detail: parallel fan-out across multiple sources, return field specifics, GDELT→GNews fallback chain, and the patent soft-fail. This goes well beyond the annotation baseline and fully discloses the tool's behavior.

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

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

The description is dense but well-structured: front-loaded with the core purpose, followed by source detail, return fields, and constraints. The many example phrases are somewhat redundant but not harmful. Every sentence adds value, though it could be trimmed slightly without losing meaning.

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

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

For a complex tool with no output schema, the description enumerates all major return components (CIK, filings, fundamentals, patents, news, LEI) and includes important caveats (patents sunset, name unsupported). Combined with the rich annotations, the description is fully complete for an agent to use 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 description coverage is 100% and the schema already documents both parameters ('type' enum, 'value' with ticker/CIK examples and name unsupported). The description repeats the same parameter guidance without adding new meaning beyond what's in the schema, so the baseline of 3 applies.

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

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

The description clearly states a specific verb+resource: 'full cross-source profile of a US public company' and details the exact data returned (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name input.

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 for holistic views, prefer over chaining lookups, and exclude names ('names not supported — use resolve_entity first if you only have a name'). The description also mentions soft-fail behavior for patents due to API sunset, offering clear when-to-use and when-not-to-use context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds little beyond the obvious 'Delete' action, but it does clarify that it removes previously stored memory and can be used to clear sensitive data. 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?

Two short sentences deliver the essential info: what it does, when to use it, and related tools. Every word earns its place, and the critical verb 'Delete' is front-loaded.

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

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

For a simple one-parameter destructive tool, the description covers the what, when, and related operations. No output schema is needed for a delete operation, and the usage guidance is sufficient. Minor gap: no mention of behavior for non-existent keys, but idempotentHint covers that implicitly.

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

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

Schema coverage is 100% with the key parameter described as 'Memory key to delete.' The description adds no extra detail about the parameter beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember and recall, which are explicitly mentioned as counterparts.

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 use cases: stale context, task completion, or clearing sensitive data. It also mentions pairing with remember and recall. However, it does not explicitly state when not to use the tool or name alternative tools as a primary choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is known. The description adds process details (fetches the page, extracts title/description/key links, emits standard markdown) and output format (single text blob), which go beyond the annotations.

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

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

The description is three sentences, front-loaded with the core action, followed by process and use cases. Every sentence earns its place, with no redundant or vague phrasing.

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 two well-documented params and strong annotations, the description covers purpose, process, output, and use cases. It could mention limitations (e.g., public URLs only) or error handling, but these are not essential given the simplicity and the openWorldHint annotation.

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 parameters are well-documented. The description reinforces that the tool works for 'any URL' and mentions extraction of title/description/key links, but it does not add significant new meaning beyond what the schema already provides.

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

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

The description clearly states the tool's function with a specific verb ('Generate') and resource ('llms.txt file for any URL'), and explicitly mentions AI crawlers as the audience. It differentiates itself from sibling tools like scan_competitor_ai_presence by focusing on generating a standard file format with concrete use cases.

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 'Useful for' section spells out when to use this tool: getting a client's site indexed, drafting llms.txt for a project, or auditing a competitor's AI visibility. It does not explicitly mention exclusions or alternatives, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. Description adds value by disclosing scope (caller's subscriptions), return fields, and the active-only default with the include_inactive option – useful behavioral context.

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

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

Two sentences, front-loaded with purpose and return fields, followed by actionable usage guidance. Every word earns its place, 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 list tool with one optional parameter and no output schema, the description fully covers purpose, return fields, and usage context. Combined with the comprehensive annotations, there are no significant gaps.

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

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

Schema coverage is 100% with the include_inactive parameter well-described in the schema. The description does not add parameter-specific details beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description states 'List the caller's active subscriptions' – a specific verb (list) + resource (subscriptions) with scope. It clearly distinguishes from siblings like subscribe and unsubscribe by being the read-only enumeration tool.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more' and 'to find an id to cancel'. Does not explicitly mention when not to use it, but the listed scenarios are clear and relevant to sibling 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 adds value by enumerating the returned metadata fields (columns, types, row count, category, last-updated), complementing the readOnlyHint and idempotentHint annotations. It does not contradict the annotations, and no side effects or error behavior are relevant for a read-only operation.

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

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

The description is a single, front-loaded sentence with an example, conveying all necessary information without wasted words. It is concise and easy to parse.

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

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

For a simple one-parameter metadata lookup, the description fully covers the purpose, required input, and return contents. Since there is no output schema, the description appropriately carries the burden of explaining what the tool returns.

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

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

Schema coverage is 100% with a clear description and example for resource_id. The tool description repeats the same example and parameter name, adding no new semantics beyond what the input schema already provides.

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

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

The description clearly identifies the action ('Get') and the resource (dataset schema + metadata), and specifies the required input (resource_id). It is distinct from data querying tools by emphasizing schema and metadata, but does not explicitly name or contrast sibling tools like 'query' or 'datasets'.

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

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

Usage is implied: you need a specific resource_id to retrieve schema and metadata. However, there is no explicit guidance on when not to use this tool or which alternatives to prefer for data rows or dataset listings.

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

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

Annotations provide only false hints, so the description carries full disclosure burden. It discloses rate limiting (5 per identifier per day), quota exemption, the claim_token return/redeem workflow, and daily human review. These details go far beyond the bare annotation fields and are consistent with 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 long but each sentence earns its place—scope restrictions, claim-token mechanics, rate limits, and quota semantics are all operationally relevant. It is slightly dense and could be tightened, but the length is justified by the tool's non-trivial feedback/claim-token flow.

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

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

With no output schema and no required parameters, the description still explains what happens on filing (claim_token), how to follow up, quota constraints, and scope exclusions. It gives enough context for an agent to safely invoke the tool and handle its return value without additional assumptions.

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 adds significant meaning: it explains type categories in plain language, tells users to reference Pipeworx tool/pack names rather than prompts, and describes the claim_token's full lifecycle including example usage. This materially improves parameter understanding beyond 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 a specific verb-plus-resource phrase: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories and explicitly distinguishes itself from siblings by restricting use to tools from this Pipeworx connection, directing other-server issues elsewhere.

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

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

Usage guidance is explicit and comprehensive: bug, feature/data_gap, and praise triggers are stated, and what not to do is directly covered—do not report tools from other MCP servers, and do not paste end-user prompts. It even names the alternative action ('file it with that server instead'), making exclusion criteria unambiguous.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This discloses data source, privacy, and caching behavior, which is useful for the agent to know the freshness and reliability of the data. This exceeds what annotations alone provide.

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

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

The description is concise and well-structured: the first sentence states the core purpose, the second lists explicit use cases, and the third adds technical caveats. Every sentence earns its place, and there is no repetitive or redundant wording. It's appropriately sized for the tool's simplicity.

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 optional parameter and no output schema, this description is quite complete. It explains what the tool returns (top tools, packs, call volume), the data source and privacy (no PII), and caching variability. It does not give a full return structure, but it does specify the data components ('(pack, tool, count)'), which is sufficient for an agent to understand the output concept. Combined with the strong annotations, the description adequately covers the essential context.

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

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

The input schema already fully describes the single 'window' parameter with enum values and a semantic explanation: '24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.' The tool description mentions the window options but adds no extra meaning beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is specific with a verb ('Returns') and resource ('top tools, top packs, total call volume'), and it distinguishes itself from siblings like ask_pipeworx or query by focusing on aggregated agent usage trends 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 explicit use cases: 'Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice before asking your own question, (3) seeing whether your use case aligns with what most agents need.' These are clear contexts for when to use the tool. It doesn't explicitly mention alternatives or when not to use it, but the use cases effectively imply that it's for pre-query discovery and validation rather than direct information retrieval.

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

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses significant behavioral details: partition placeholder filtering, similarity thresholds, fill-check pricing against live CLOB depth, and a warning that 'realizable_edge_pp ≤ 0... do not trade it.' 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 information-dense; each section (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) earns its place for a complex tool. Minor redundancy exists but is acceptable given the tool's sophistication.

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 two modes, filters, semantic checks, and no output schema, the description comprehensively explains the response structure (opportunities[], partition_check fields), fill-check logic, and when signals are invalid. For a tool this complex, nothing essential is missing.

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

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

Although the input schema already describes both parameters well, the description adds substantial meaning: concrete slug examples, what each mode walks/computes, how 'topic' searches related events, and the semantic anchor/Jaccard constraint. This goes far beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_fill_risk by defining its core detection method, and the multiple modes (trending_scan, event, topic) make its scope explicit.

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

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

The description gives direct when-to-use guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends event mode for specific markets, explains cross-event scanning rationale, and explicitly points to polymarket_fill_risk for custom sizing, thereby covering both usage and alternatives.

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

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

Despite annotations already covering safety (readOnly, idempotent, non-destructive), the description adds extensive behavior: three response segments, per-leg edge calculation, Kelly fractions, 24h-move warning, Fed bet exclusion rationale, caching at 1h, and diagnostics for empty segments. This goes far beyond the annotations.

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

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

The description is long but front-loaded with a clear purpose and uses uppercase headers to organize segments, knobs, and response structure. Every sentence adds unique information, though the density makes it less concise than ideal.

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

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

No output schema exists, but the description thoroughly documents the return structure (by_segment, fed_candidates, _diagnostics), opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and caching behavior. Given 9 parameters and no output schema, this is a complete description that would let an agent 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% with detailed parameter descriptions, so the baseline is 3. The main description does group parameters into 'TRADEABLE-EDGE KNOBS' and explains how min_partition_leg_kelly applies to per-leg Kelly, but this is largely redundant with the schema. It adds minimal semantic value beyond what the input schema already provides.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today') and implicitly distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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

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

It clearly states the tool is 'Built for "what should I bet on today"' and explains that it avoids paging hundreds of markets. However, it does not explicitly mention when not to use it or compare to alternative tools like polymarket_arbitrage or polymarket_edge_tracker, 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?

The description goes well beyond the readOnly/openWorld/idempotent hints by disclosing the 60-day snapshot TTL, that snapshots are only written on cache-miss (causing data gaps), and that decay is computed from daily closes of edge_pp_net (not intraday). These are important behavioral details not present in annotations, and there is no contradiction.

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

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

The description is well-structured with clear sections (intro, args, response, limits). Every sentence adds unique information, and the length is justified given the tool's complexity and the absence of an output schema. No fluff 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?

Since there is no output schema, the description takes on the responsibility of explaining return values, and it does so thoroughly: tracked[], expired[], snapshot_dates[], their fields, and data caveats (TTL, gaps, slippage). This is a complete picture for an agent to invoke the tool correctly.

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

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

Both parameters are fully described in the input schema (coverage 100%) with defaults and clamping. The description merely repeats these defaults ('default 14, max 30', 'default 1wk') without adding new semantic meaning beyond 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?

Description clearly states it provides 'edge persistence and decay telemetry' and answers the question 'how long has this edge existed and is it shrinking?', distinguishing it from sibling polymarket_edges which likely focuses on current edges. The significance is explained with the fresh vs. old wide edge example.

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

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

The description clearly frames when to use the tool via the question it answers and the conceptual 'competition clock' median lifespan. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for a user to infer its role relative to siblings like polymarket_edges.

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 and non-destructive behavior; the description adds substantial depth by detailing what the tool computes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc.), what triggers degraded vs cannot_fill, and the forced_directional_risk naming. It clearly indicates this is an analytical check, not an execution tool, and describes edge-case behavior 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 long but every sentence earns its place. It is front-loaded with the core purpose, then uses clear uppercase labels (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) to structure complex multimodal behavior. No fluff or redundancy; it remains efficient despite its density.

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 modes, 4 parameters, no output schema), the description is exhaustively complete. It covers both modes in detail, lists all return fields, explains interpretation of verdicts and risk factors, and situates the tool within the broader trading workflow. No critical aspect is left ambiguous.

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

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

Although schema coverage is 100%, the description enriches every parameter's meaning. It explains the market vs event mode distinction, default side behavior in basket mode, and the nuanced interpretation of size_usd (max spend for buys, target proceeds for sells; settlement notional for baskets). It also notes the clamp range and the meaning of output fields, adding significant value beyond the raw schema.

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

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

The description opens with a precise, specific verb+resource ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes this from sibling tools by explicitly stating it should be used before polymarket_arbitrage or polymarket_edges trades. It enumerates both single-market and basket modes with distinct outputs, making the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the rationale (thin books not capturable) and the risk of partial fills, effectively covering alternatives and exclusions.

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

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

Annotations already signal read-only and idempotent behavior, but the description adds rich detail: the two compatibility_warning scenarios, temporal_alignment field semantics, and skipped_cross_type/subtype counters. This goes far beyond what annotations provide, disclosing exactly what the tool reports and why.

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

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

The description is long, but every sentence serves a purpose. It is structured into TWO MODES, RESPONSE, and SAFETY FIELDS, making it scannable despite the density. No redundant or filler content; the warning about real-world tradeability is essential guidance.

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

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

With no output schema, the description must explain the return value, and it does: leg-by-leg prices, spread list, top_spreads_pp, compatibility_warning, temporal_alignment, and the skip counters. It also covers edge cases and limitations, making it complete 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining how the 'topic' param maps to pre-mapped shortcuts, how explicit tickers override the topic, and that the parameters are mutually exclusive per mode. This enrichment justifies a score 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 clear statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This is a specific verb+resource pairing that distinguishes it from sibling tools like polymarket_arbitrage, and the rest of the description reinforces the unique cross-venue focus.

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 describes two modes ('topic' and explicit ticker/slug) and gives guidance on when spreads are meaningful versus when compatibility_warning fires, including the caution that 'pre-mapped ≠ tradeable.' It doesn't name alternative tools explicitly, but the usage context is clear enough for an agent to decide when to invoke this 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 provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety traits. The description adds useful nuance: returns matching rows as JSON and SoQL clauses should omit the leading '$'. This goes beyond the schema but does not detail error handling, rate limits, or pagination behavior comprehensively.

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, with no fluff or repetition. The first sentence clearly states the purpose, the second lists clauses, and the third covers the return format. It is slightly more verbose than the tightest descriptions but is well-structured and front-loaded.

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

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

For a query tool with 7 parameters and no output schema, the description covers the essential return type (JSON), the query syntax, and the target resource. The schema examples fill in usage patterns. Missing details like defaults or error handling are minor for this context, and annotations cover safety.

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

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

Schema coverage is 100%, with each parameter having a description and examples. The description reiterates the main clause types and adds the '$' omission rule, which is a small extra. It does not significantly compensate beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool runs a Socrata SoQL query against an Oregon Open Data dataset by resource_id, naming the resource and specific operation. It distinguishes itself from siblings like 'datasets' (which lists datasets) and 'metadata' by focusing on data retrieval with filtering capabilities.

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 context is explicit: use this tool when you need to query a specific dataset using SoQL clauses. However, it does not provide explicit alternatives or when-not-to-use scenarios, such as mentioning 'datasets' for discovering resource_ids or 'search_within' for simpler searches.

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, covering safety. The description adds useful behavior: scoping to 'anonymous IP, BYO key hash, or account ID' and the dual mode (retrieve vs list all keys). This enriches understanding beyond annotations.

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

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

Three sentences, front-loaded with the primary action, then use case and scoping. No redundant filler; every sentence adds value. Efficient 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?

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and sibling relationships. It doesn't explain the return format, but the tool's function implies the saved value or list, and the description is sufficient for effective invocation.

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

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

Schema coverage is 100%, with the key parameter described as 'Memory key to retrieve (omit to list all keys).' The description echoes this and adds minor context ('previously saved via remember'), but doesn't significantly go beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('retrieve') and resource ('value/key list'), and distinguishes itself from sibling tools by explicitly pairing with 'remember' and 'forget'.

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

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

The description provides explicit usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives: 'Pair with remember to save, forget to delete.' This clearly indicates when to use this tool versus 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 description discloses a state-changing behavior (mark_read:true flags events as read) that contradicts the readOnlyHint annotation. Per the rubric, a contradiction leads to a score of 1, even though the description otherwise adds useful context.

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

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

The description is three sentences, front-loaded with the core function, and every sentence contributes: payload contents, filtering options, mark_read semantics, and polling note. 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?

With no output schema, the description adequately describes the return payload (source, citation_uri, raw event), filtering, and polling. It omits explicit pagination details, but the limit parameter is covered in the schema, making it reasonably complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds an example type ('sec_8k'), clarifies the 'since' expected format, and explains the downstream effect of mark_read (next call shows only newer events), providing value beyond the schema.

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

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

The description clearly states the action ('Pull fired events from your subscription feed') and specifies the resource. It also enumerates the payload fields, distinguishing it from sibling tools like list_subscriptions, which focus on subscriptions themselves rather than fired events.

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 explains the polling use case and mentions an alternative HTTP endpoint for scripts/dashboards, giving clear context for when to use this tool interactively. It doesn't explicitly compare with sibling tools, but the context is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail until reactivated), and the exact return shape (changes[], total_changes, pipeworx:// URIs). This adds substantial behavioral context.

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

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

The description is dense but every sentence earns its place: query paraphrases, source fan-out with fallback behavior, parameter format, return values, and sibling alternative. It is front-loaded with user intent, making it easy to parse.

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

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

Given the tool's complexity (multiple sources, fallback logic, date-shorthand, return schema absent), the description covers all critical aspects: input formats, source behavior, failure modes, and output structure. Nothing essential is missing.

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

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

Schema coverage is 100%, so the parameters are already fully documented. The description repeats the `since` shorthand examples and ticker/CIK formats but adds no new meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: a change feed for a company over a time window, citing specific examples of user queries. It distinguishes from the sibling tool entity_profile by explicitly noting when to use that alternative for a static 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?

Provides explicit query patterns ("What's new with X") and an explicit alternative: 'Use entity_profile instead when you want the static profile...' This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (idempotent, non-destructive), the description adds crucial details about scoping ('scoped by your identifier') and persistence ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). These are behavioral traits not covered by annotations and materially affect agent expectations.

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

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

Five short sentences, each contributing a distinct fact: purpose, usage trigger, storage format, persistence behavior, and related tools. No redundancy or filler. Information is front-loaded with the core purpose in the first sentence.

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

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

This is a simple 2-parameter tool with no output schema required. The description covers what, when, how (key-value), scoping, persistence, and related operations. It is fully complete for its complexity; no meaningful gap remains.

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% (both key and value are fully described). The description adds context by calling it a 'key-value pair' and mentioning scoping, but does not introduce new parameter-specific meaning beyond the schema. Baseline of 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: 'Save data the agent will need to reuse later.' It clearly distinguishes from siblings by mentioning recall (retrieve) and forget (delete) as complementary tools, making the purpose unmistakable.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives (recall, forget) and provides context about sessions and persistence. This gives clear selective guidance.

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

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

The description adds substantial behavioral detail beyond the annotations. It discloses that unresolved identifiers are explicitly listed under `unresolved` rather than omitted, that LEI/FIGI enrichment degrades gracefully (fallback to EDGAR if GLEIF/OpenFIGI unavailable), that each call cascades through multiple endpoints, and that identifiers are labeled with their source. These are non-obvious traits the agent would otherwise not know.

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 appropriately sized for the tool's complexity. It is front-loaded with example queries and a one-sentence summary, then structured with SUPPORTED TYPES. Every sentence adds relevant information—no filler or redundancy. The length is justified by the need to explain multiple identifier sources and fallback behavior.

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?

There is no output schema, so the description must explain return values, and it does thoroughly. It details what each type returns (CIK, ticker, LEI, FIGI, ownership for company; RxCUI, ingredient, brand for drug) and mentions citation formats. It also covers failure modes (unresolved identifiers, graceful degradation). This gives the agent a complete picture of the tool's capabilities and limitations.

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 value by explaining the `type` parameter in context (company vs drug) and specifying that `value` accepts different forms (ticker, CIK, name for company; brand or generic for drug). It also provides examples that clarify expected input formats, going beyond the schema's brief description.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific examples ('ticker for...', 'CIK for...') and distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID.' It also breaks down supported types (company, drug) with specific identifier outputs, making it 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 gives explicit guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and mentions that it replaces 2-3 manual lookups. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it appropriately in most cases.

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

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

Annotations already declare readOnly, openWorld, idempotent, etc. The description adds behavioral detail: it internally calls ai_visibility_check, ranks by score, and returns score/confidence/signal density. It also notes the first entity is treated as the 'subject' in the schema, which is duplicated. Overall it complements 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?

Three sentences: opening action, mechanism, use case, and output. Front-loaded with the core purpose, each sentence delivers new value with no fluff.

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

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

Despite no output schema, the description explains return fields (score, confidence, signal density). With schema covering parameters and annotations covering safety, the description is complete enough for an AI agent to decide invocation. Minor omission: no mention of the 'models' behavior, but that is schema-covered.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaningful parameter semantics beyond what the schema already provides; the 'first entity as subject' nuance is already in the schema. No extra value from description.

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

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

The description states a specific verb ('Compare') and resource ('AI visibility across multiple entities'), with clear output (ranked list, most/least recognized). It distinguishes itself from the sibling ai_visibility_check tool by explicitly mentioning it probes each entity with ai_visibility_check and compares side-by-side.

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 use case ('competitive AI-marketing audits') and an example query. Implicitly differentiates from ai_visibility_check (single entity) by emphasizing 'multiple entities side-by-side', but does not explicitly name alternatives or exclusions.

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

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

Beyond annotations, the description discloses important behavioral traits: it fans out to external services, first measurement on a new version can take 5-30s, and partial failures degrade gracefully with sources_failed reporting. It also outlines the return structure. Annotations indicate read-only/idempotent, and the description aligns without contradiction.

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

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

Although the description is long, it is dense with necessary operational details: purpose, trigger phrases, output fields, ecosystem scope, and failure handling. Every sentence earns its place, and it is efficiently structured with dashes and clauses rather than 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 no output schema, the description enumerates return fields in prose, covers latency and timeout behavior, and specifies ecosystem limitations. It gives an agent everything needed to select and 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 fully describes both parameters (package name with scoped package handling, version with default-to-latest). The description adds no additional parameter-level semantics, so a baseline 3 is appropriate given 100% schema coverage.

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

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

The description states a specific composite check for npm packages, naming the exact sources (deps.dev, bundlephobia) and the question it answers ('should I add this npm package to my project'). It also clearly distinguishes from alternatives by declaring NPM-only in v1, which separates it from other ecosystem-specific 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives exclusion criteria for non-NPM ecosystems, directing agents to deps.dev:version instead, which is a clear when-not-to-use mandate.

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, etc.), the description discloses meaningful behavioral details: the embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), and a 200K char cap with truncation flagging. It also mentions output characteristics (offsets for verbatim quote verification). This adds substantial value beyond structured fields.

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

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

The description is four sentences, each earning its place: core action, usage condition, paired workflow, and technical caveats. It is front-loaded with the most important information and contains no fluff. Despite being longer than the minimal example, it remains efficient and well-structured 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?

The description is complete despite no output schema: it explains what the tool returns (top-N passages with offsets and similarity scores), the use case, the truncation behavior, and how it fits in the broader tool ecosystem. Given the 3-parameter schema and rich annotations, the description covers all necessary context for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces parameter meaning with examples ('SEC 10-K body, an article, a long tool result') and explains the purpose of the text parameter, but it does not add new semantic detail beyond what the schema already provides. No extra insight about 'limit' is given.

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

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

The description clearly states the tool performs semantic search inside a previously fetched record, using specific verb and resource ('Semantic search INSIDE a fetched record'). It distinguishes from siblings by emphasizing 'inside' already-pulled text and explicitly pairs with ask_pipeworx_grounded for the grounded answering step, making its unique role evident.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also provides a paired alternative workflow with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This constitutes both a positive usage condition and an alternative, fulfilling the when/when-not/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?

The description adds substantial behavioral context beyond annotations: requires OAuth, SMS phone verification and 10/day cap, webhook signing secret exposure, and auto-disable after 10 consecutive failures. It does not contradict the annotations (openWorldHint, idempotentHint, etc.) and significantly clarifies the side effects and prerequisites.

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 with examples and constraints, which makes it longer than typical, but every sentence carries useful information. It is front-loaded with the core purpose and uses structured formatting (colons, examples) that aids readability. Slightly long but 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?

For a tool with nested objects, multiple subscription types, and delivery complexities, the description covers all necessary context: type-specific params, delivery channel behavior, auth requirements, output, and failure handling. Even without an output schema, it clearly states the return value and edge cases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and the description goes further by giving concrete examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and elaborating delivery options (email, SMS, webhook). This adds meaning beyond the schema's generic descriptions.

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

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

The description clearly states the verb ('Create') and resource ('a proactive monitoring subscription to a live-data event stream'), and specifies it returns the new subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe by emphasizing the creation/persistence aspect.

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

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

It explicitly explains when to use the tool (to monitor live-data streams) and provides constraints (requires Pipeworx OAuth, anonymous/BYO cannot persist). It also offers an alternative for reading alerts (feed/pull via recent_alerts), giving clear context for choosing between proactive subscription vs on-demand retrieval.

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 non-destructive behavior, so the description doesn't need to restate safety. It adds valuable behavioral context: the tool draws from a 'live catalog of thousands of tools,' returns category-bucketed examples, and that each example includes the exact tool+argument shape. This explains what the agent will receive and why it is a useful onboarding tool beyond what annotations convey.

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

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

The description is dense but every sentence contributes useful information: user-intent phrasings, purpose, return contents, category list, parameter behavior, and a clear usage directive. It's somewhat long and starts with a run-on list of user queries, but it front-loads recognizability and remains information-dense without significant redundancy.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description is remarkably complete. It explains the purpose, what the agent will receive (category-bucketed examples with tool+argument shapes), how to invoke it (with or without topic), and when to use it (first, when onboarding). It even positions it relative to sibling meta-tools, making selection unambiguous.

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

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

Schema description coverage is 100%: the schema already documents the optional `topic` parameter with its allowed values and the behavior when omitted. The description adds example values ('finance', 'pharma', 'betting') and reinforces the call-with-no-arguments behavior, but this is marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the onboarding entry point for the Pipeworx agent, explicitly stating it returns category-bucketed example questions with the exact tool and argument shape to answer them. It distinguishes itself from siblings by positioning itself as the 'first' tool to use when the agent doesn't know what Pipeworx can do, and it even names the more specific meta-tools like ask_pipeworx and entity_profile.

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

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

The description gives an explicit usage directive: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides invocation guidance for the optional topic parameter and describes the no-argument behavior. While it doesn't list every 'when-not' scenario, the 'first' framing implicitly tells the agent to move on to more specific tools once it has learned what's available.

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

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

The description discloses important behavioral traits beyond the annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This adds significant context while remaining consistent with the annotations (e.g., destructiveHint=false).

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 tight sentences, each adding value: the action, the ownership constraint, and the deactivation behavior. No waste, front-loaded with the main 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 single-parameter mutation tool with no output schema, the description fully covers what the tool does, its constraints, and its downstream effect on recent_alerts. It is complete and self-contained.

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

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

The input schema already fully describes the sole parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description does not add new meaning beyond referring to the same id, so the baseline of 3 applies for high schema coverage.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from sibling tools like subscribe and list_subscriptions. The verb 'cancel' is specific and the subject is 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?

It provides a key usage condition ('you can only cancel your own subscriptions') and implies the tool is for canceling subscriptions, but does not explicitly mention alternatives or when to prefer another tool (e.g., list_subscriptions before canceling). This is clear context without exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds substantial behavioral context beyond these annotations: the meaning of each verdict, the distinction between could_not_verify and unsupported, the error object verification_error{stage,detail}, the citation format, and how tolerance_pct overrides implied wording. This is rich, non-redundant behavioral disclosure.

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

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

The description is longer than average, but every sentence adds value: query patterns, usage context, routing behavior, return value details, and an important caller caveat about could_not_verify. It is front-loaded with natural-language queries and well structured. Slightly verbose but justified by 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?

With no output schema, the description must explain return values, and it does: verdict enum, actual value with citation, reasoning, and error semantics. It also covers routing, source coverage, and performance benefits. For a tool of this complexity, the description 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 both parameters thoroughly. The description does add context for tolerance_pct ('default implied by wording, capped at 5') and gives an example for claim, but these mostly mirror the schema's own descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly specifies the tool's function: natural-language claim verification against authoritative sources ('Is it true that…' / 'fact check' / 'verify the claim that…'). It distinguishes itself from sibling tools by naming the exact use case (checking factual correctness) and describing the structured SEC path for company-financial claims versus the grounded pipeline for all other claims.

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 this tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains how different claim types are routed (SEC/XBRL fast path vs. grounded pipeline), but it does not explicitly name alternatives or exclusion criteria, so it falls just shy of full when/not-when guidance.

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