dogceo

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds important context beyond this: the default Workers AI model is free, probing Anthropic requires a BYO API key with direct payment, and the return format is specified per-model. This is valuable additional behavioral transparency.

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

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

The description is succinct and front-loaded with the main purpose. It covers cost implications, return format, and use cases in a compact manner, though a bit more trimming could make it cleaner. Still, each sentence adds value.

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

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

For a read-only probe tool with well-documented parameters and safety annotations, the description covers the essential aspects: purpose, return format, cost implications, and use cases. It lacks edge-case guidance (e.g., unsupported model names) but 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?

The input schema already documents all four parameters thoroughly (100% coverage), including the conditional need for _apiKey when 'anthropic' is in models. The description adds little new parameter meaning beyond the schema, so the 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility per model with a specific verb ('probe') and resource ('LLMs'). It provides use cases like AI-marketing audits and competitive monitoring, but it does not explicitly differentiate from sibling tools such as scan_competitor_ai_presence.

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 indicates when the tool is useful ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for usage. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context: routing across many tools, automatic argument filling, stable pipeworx:// citation URIs, and works on every tier. Minor gap is not detailing failure modes or latency beyond 'one fast call', but this is sufficient given 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 dense and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), followed by scope, examples, and escalation paths. Some repetition exists ('START HERE' and 'default entry point' say the same thing), but every major section earns its place.

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

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

For a complex routing tool with no output schema, the description fully covers what the tool does, when to use it, what it returns, and how it compares to siblings. Examples clarify the expected input format, and the mention of citation URIs covers return-value expectations.

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 fully documents all six parameters as aliases for 'question'. The description provides examples but adds no semantics beyond what the schema already states; it does not explain formatting, length limits, or language requirements. 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 states a clear verb ('routes', 'returns') and a specific resource ('5,708 tools across 1,494 verified sources'), and it explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research. This leaves no ambiguity about what the tool does.

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

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

It gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), enumerates trigger phrases and example queries, and names alternatives with the conditions for stepping up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions).

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 read-only, idempotent, open-world, non-destructive hints. The description adds meaningful behavior beyond those annotations: candidate routing may be live, currently no candidate is active, and it is a full working router rather than a fallback—valuable context for trusting and using the experimental variant.

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

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

The description is compact and front-loads the key distinction (beta, identical router, experimental improvements). Minor redundancy exists: 'matches ask_pipeworx exactly' appears twice and the retirement date is unnecessary operational detail, but overall every sentence earns its place.

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

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

The description names the sibling it mirrors, states current parity, and clarifies response/argument equivalence, making the tool callable with just a question. Since the output schema is absent, referencing the shared response shape with ask_pipeworx provides sufficient context, though it does not enumerate the response format itself.

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 six parameters and aliases at 100% coverage. The description only restates that arguments match ask_pipeworx, adding no new parameter-level meaning, so the 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 a beta version of ask_pipeworx: a universal router over the same 5,708 tools with candidate routing improvements. It distinguishes itself from the stable sibling by emphasizing its experimental edge, so an agent can tell it apart from ask_pipeworx and ask_pipeworx_grounded.

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

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

It explicitly says to use it exactly like ask_pipeworx when wanting the newest routing and notes results are compared against the stable router. It does not spell out when to prefer the stable alternative instead, but the beta-vs-stable framing gives clear contextual guidance.

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

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

Annotations already signal read-only and idempotent behavior, but the description adds meaningful operational detail: it routes across 5,708 tools, extracts answers only from tool results, returns verbatim evidence, and explicitly refuses rather than inventing data. It even discloses the extra LLM-call cost, which is not inferable from annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, return contract, refusal modes, usage policy, and cost trade-off. Key information is front-loaded, and there is no redundant restatement of the tool name or schema content.

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

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

Even without an output schema, the description fully specifies the success return shape and all refusal reasons, while also giving routing scope and an explicit cost/use heuristic. An agent has everything needed to decide, invoke, and interpret the result correctly.

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

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

The input schema covers 100% of parameters, documenting the main 'question' field and five aliases. The description adds only 'question in natural language', which is already implied by the schema descriptions. Baseline 3 is appropriate because 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 defines the tool as a hallucination-resistant, evidence-based answer mode for high-stakes reads, making its primary purpose unmistakable. It explicitly names the sibling 'ask_pipeworx' and positions itself as its stricter counterpart, which distinguishes it from related tools without needing to inspect schemas.

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

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

It provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on') and directly names the cheaper alternative for casual lookups ('prefer ask_pipeworx'). This is a clear decision rule for an agent selecting between 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?

Beyond the read-only/idempotent annotations, the description discloses resolver confidence handling, fan-out behavior, response shapes, fallback mechanisms, closed/inactive market short-circuits, wide-spread tradeability warnings, and cancellation rule risk (e.g., flat-50¢ void settlements). This is exceptional behavioral detail.

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?

Long but densely packed with high-value sections (classifiers, fan-out, resolver contract, safety). It is well-structured with uppercase headers and front-loaded with the main purpose. Minor length overkill but all content is relevant.

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

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

No output schema exists, so the description must explain return shapes. It details result.market, result.analysis, result.evidence, parent_event, news fallback, and blocking behaviors. Also covers edge cases like low-confidence and cancellation rules, making it fully self-contained for 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 description coverage is 100% (all 3 parameters have descriptions), so baseline is 3. The description provides examples and fan-out context but doesn't add substantial parameter-specific semantics beyond the schema.

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

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

Description clearly states it researches a Polymarket bet by pulling relevant Pipeworx data in one call, with explicit classifiers and fan-out examples. It distinguishes from siblings by focusing on data-gathering for a single market with market-vs-model comparison.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and explains when low-confidence matches block analysis. However, it doesn't explicitly name alternative sibling tools for exclusion, but the context is clear.

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 the return format ('array of image URLs'), adding value beyond the annotations' read-only and idempotent hints. It also gives examples of valid inputs, though it doesn't cover edge cases like unknown breeds or count behavior, which are handled by the schema.

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

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

The description is two sentences, front-loaded with the core action and resulting format, with zero filler. It's a model of brevity.

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

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

Given the tool's simplicity, the 100% schema coverage of parameters, and the presence of an output schema, the description covers the essential purpose and use case. The only minor omission is explicit mention of default count, but that's 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 description coverage is 100%, so parameters are fully documented in the schema. The description adds example values ('labrador', 'poodle') and implicitly references valid breed names, but adds no additional parameter semantics beyond the schema.

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

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

The description uses the specific verb 'Get' with a clear resource ('multiple dog photos') and scope ('for a specific breed'), supported by concrete examples. This clearly differentiates from sibling tools like random_breed_image (single random) and list_breeds (which enumerates breeds).

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 phrase 'Use when you need a gallery of one breed' provides a clear use-case scenario. It implies distinction from random image tools, though it doesn't 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?

Annotations already declare the operation is read-only/idempotent/non-destructive. The description adds meaningful behavioral details beyond that: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, automatic sorting by primary metric, and citation URIs in the response. This significantly improves the agent's ability to predict 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?

The description is front-loaded with natural-language trigger examples, then flows into precise behavioral details. Every sentence contributes information: type-specific data sources, sorting behavior, return format, and efficiency gains. Though longer than the minimal example, it remains efficiently structured with no filler.

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

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

Given no output schema, the description sufficiently describes what the agent will receive (paired data + citation URIs) and how results are ordered. It also covers edge cases like off-calendar fiscal years and specifies the allowed count range, making the tool fully contextualized without needing extra documentation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra value by explaining what each type pulls (10-K financials vs. adverse-event/trial counts) and clarifying the expected shape of values (tickers/CIKs vs. drug names), which goes beyond the schema's simple enum and array definitions.

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 explicit trigger phrases and states a precise function: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." This clearly distinguishes it from sibling tools like single entity_profile lookups.

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?

Directly instructs "ALWAYS PREFER over sequential single-pack lookups" when comparing entities, and characterizes the tool as replacing 8–15 sequential lookups. This explicitly tells the agent when to choose it over 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?

With readOnlyHint and idempotentHint already present, the description goes well beyond them: it discloses account and plan requirements, latency, gaps[] behavior with a never-invented guarantee, contradictions[] handling, semantically excerpted records, hop/citation fields, and fetchable citation URIs. None of this contradicts 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 definition is long but every sentence earns its place: auth, alternatives, scope, output packet, limitations, depth semantics, citation guarantees, and timing are organized and front-loaded. There is no filler; the length is proportionate to 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?

There is no output schema, yet the description fully describes the return packet, gaps[], contradictions[], hop and citation_uri fields, and caveats about the structured catalog. It also covers auth, pricing, and performance expectations, so an agent has everything needed to decide and call 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's own parameter text already explains question decomposition and the depth enum including the paid tier. The narrative adds conceptual context for depth, but almost all of it restates the schema rather than adding new parameter-level information.

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 names a specific, compound operation: grounded multi-source research across Pipeworx's 1494 structured data sources with decomposition and parallel routing. It explicitly separates itself from open-web search and from the ask_pipeworx sibling, making the tool's identity and scope unmistakable.

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

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

It gives explicit selection criteria: best for broad/multi-part structured-data questions; use ask_pipeworx for single lookups, breaking/live-news topics, or when not signed in. The description also tells the agent what will happen if the tool is used on an out-of-catalog topic, mostly empty gaps[], which is exactly the when/when-not guidance needed.

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

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

Annotations already declare readOnlyHint and idempotentHint true, so safety is covered. The description adds valuable behavioral detail beyond annotations: it returns top-N tools with names, descriptions, and full input schemas, and states 'each result is ready to call directly, no second schema lookup needed.' This clarifies the output and interaction model, which is not inferable from 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 front-loaded with the core purpose, then provides the domain list, return value, and usage timing. Every sentence contributes, though the domain list is lengthy. Slightly long but still 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?

The description fully covers what the tool does, when to use it, what it returns (top-N tools with schemas), and that results are directly callable. Given there is no output schema, the description compensates by explicitly stating the return format. It is complete for a meta-tool with 6 parameters.

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

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

Schema description coverage is 100%, with all 6 parameters fully described in the input schema, so the baseline is 3. The description text does not add parameter-specific meaning beyond the schema, though it does reinforce the 'query' concept with examples and aliases. No additional clarification is needed.

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

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

The description clearly states the tool's purpose with a specific verb+resource: 'Find tools by describing the data or task.' It explicitly differentiates from siblings by positioning itself as a meta-tool for discovering all available tools, with a clear list of domains covered and an instruction to 'Call this FIRST.'

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 on when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It also clarifies the alternative—that this is for option discovery rather than just one answer—which distinguishes it from direct-answer 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 discloses significant behavioral traits: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; specific return fields; patents API sunset with soft-fail; GDELT→GNews fallback; and name-unsupported limitation. These go well beyond the annotations (readOnly, openWorld, idempotent) by explaining actual data sources and failure modes.

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

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

The description is lengthy but well-structured and front-loaded: examples, core purpose, usage guidance, then return components. Every sentence contributes unique information, with no filler or repetition.

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

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

With no output schema, the description thoroughly explains the return structure (CIK, company_name, recent_filings with URIs, fundamentals with specific fields, patents, news via fallback, LEI). It covers edge cases (patents soft-fail, name unsupported) and external references, making it complete for a complex data-fetching tool.

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

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

Schema description coverage is 100%, and the input schema already contains the same details for 'value' (ticker or zero-padded CIK, names not supported, use resolve_entity). The tool description repeats this verbatim, adding no new semantic meaning beyond the schema. The 'type' parameter is also fully described in the schema.

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

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

The description states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' with specific examples like 'Tell me about X' and 'company profile for Microsoft.' It clearly differentiates from siblings by recommending it over chaining single-pack SEC/XBRL/news lookups, and explicitly mentions resolve_entity for name-based lookups.

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity first if only a name is provided, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds the usage context (stale/task done/sensitive data) but does not disclose additional behavioral traits like irreversibility or idempotent behavior beyond what annotations imply. With annotations covering the main safety aspects, the description adds moderate value.

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

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

The description is three sentences, each serving a distinct purpose: action, usage context, and relationship to sibling tools. It is front-loaded with the core action and contains no wasted words.

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

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

For a simple one-parameter deletion tool with good annotations (destructiveHint, idempotentHint), the description covers what it does, when to use it, and how it relates to related tools. No output schema exists, and the description does not need to explain return values; it is complete for the tool's complexity.

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

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

Schema coverage is 100% for the single 'key' parameter, so the baseline is 3. The description says 'by key' which aligns with the schema documentation, but it does not add deeper semantic meaning beyond that. The description reinforces the parameter's purpose but does not significantly expand on it.

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

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

The description clearly states the tool's function: 'Delete a previously stored memory by key.' This is a specific verb (Delete) plus resource (previously stored memory) and method (by key). It distinguishes itself from related siblings like remember and recall by the explicit deletion action, and the mention of 'Pair with remember and recall' further clarifies its place among them.

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

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

The description gives explicit when-to-use guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' This provides clear context, but it does not explicitly state when not to use it or directly compare with alternatives, though the pairing with remember and recall hints at the memory-management workflow.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds meaningful process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' and clarifies the output form ('single text blob'). This goes beyond the 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 well-structured and concise. It leads with the primary action, then explains the process, the output, and lists specific use cases. Every sentence adds value, with no redundancy or filler.

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

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

The tool is moderately simple: 2 parameters with full schema descriptions, annotations covering safety, and a simple text output that the description explicitly mentions. The description also includes use cases and expected output format. It does not cover error scenarios or trade-offs, but for this complexity level, the information is sufficient 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%, with both parameters (url and max_links) already documented. The description reinforces that the tool works for 'any URL' but does not add syntax, defaults, or constraints beyond what the schema provides. Baseline 3 is appropriate since the schema carries the 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 tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the verb (generate), the resource (llms.txt file), and the scope (any URL), which distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence that focus on auditing rather than file generation.

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

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

The description provides clear usage context with 'Useful for: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly mention when not to use it or alternatives, but the use cases give sufficient guidance 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?

The description adds that it 'returns breed names and varieties,' which is a light behavioral disclosure about the return content. Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description does not contradict annotations, but it does not add deeper context like pagination or data freshness. This is adequate for a simple read-only list tool.

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

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

The description is two sentences long, with the primary action stated first. It avoids unnecessary detail and every sentence contributes value: the first defines the scope, the second gives usage guidance. 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?

For a tool with no parameters, no nested objects, and an existing output schema, the description fully covers what the tool does, what it returns, and when to use it. Annotations handle safety semantics. There are no obvious gaps that an agent would need to know to invoke this tool correctly.

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

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

The tool has zero parameters, so the schema is inherently comprehensive. The description adds meaning by indicating that the output includes breed names and sub-breeds, which helps set expectations for what the returned data represents. With no parameters, the description does not need to explain parameter semantics, and the baseline of 4 is appropriate.

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

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

The description clearly states the tool's function with a specific verb ('List') and a specific resource ('all available dog breeds and sub-breeds'). It differentiates the tool from sibling tools like breed_images or random_breed_image, which fetch images rather than list breeds.

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 explore breeds or validate a breed name before fetching images.' This indicates when it should be used (before image fetching) and indirectly distinguishes it from image-fetching tools. It does not explicitly mention alternatives or when not to use it, but the guidance is clear enough.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description need not repeat these. It adds value by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and the scope ('caller's active'). This goes beyond annotations while not 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 two sentences, front-loaded with the core action, then return details, then usage guidance. Every sentence earns its place with zero redundancy. It is concise without sacrificing clarity.

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, read-only tool with one optional parameter and strong annotations. The description covers the return format, scope, and practical use cases. It doesn't mention pagination or ordering, but for a tool like this, the provided context is nearly complete. The absence of an output schema is compensated by listing the return fields.

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 describes the only parameter (include_inactive) at 100% coverage with a clear description. The tool description adds no new parameter-level semantics beyond the schema, but it does add context for when the parameter would matter (e.g., finding an id to cancel might need inactive subscriptions). This is baseline 3 as per rubric.

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

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

The description starts with a specific verb and resource: 'List the caller's active subscriptions.' It clearly defines the scope (caller's active) and distinguishes itself from sibling tools like subscribe and unsubscribe by being the listing counterpart. It also enumerates returned fields, 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?

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel,' which indirectly reference subscribe and unsubscribe. It does not explicitly name alternative tools, but the context strongly implies when to use this tool versus adding or removing subscriptions.

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

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

The description adds valuable behavioral context beyond the (all-false) annotations: it discloses rate limiting ('Rate-limited to 5 per identifier per day'), the return of a claim_token for anonymous filings, and that the team reads digests daily. It doesn't explicitly state this is a write operation, but 'Filing' and the claim_token mechanism imply a persisted submission, consistent with readOnlyHint=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?

The description is dense but well-structured: it front-loads the purpose, then covers when to use, exclusions, the token workflow, and rate limits. Every sentence contributes useful information. It is longer than average but justified given the tool's multi-step workflow and the need to steer users away from misreporting other servers' tools.

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 covers the full usage lifecycle: what to report, how to scope it to Pipeworx tools, the anonymous claim_token flow for later status checks, rate limits, and intent. With no output schema, the description compensates by explaining the return behavior ('returns a claim_token' and how to use it). Minor gap: it doesn't describe what the direct response body looks like beyond the token, but that's adequately implied.

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 enhances the claim_token parameter by explaining its round-trip usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which is not obvious from the schema alone. Other parameters are adequately described in the schema, and the description adds use-case context for the 'type' parameter.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/report) and the resource (Pipeworx team), and distinguishes the tool from siblings by covering feedback categories (bug, feature, data_gap, praise) which no sibling tool addresses.

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 when-to-use guidance is provided for each feedback type ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...'). It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for other MCP servers. Additionally, it explains how to later check status with a claim_token.

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, openWorldHint, idempotentHint, destructiveHint), 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 sourcing, privacy, output format, and caching behavior, going well beyond what annotations provide.

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

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

The description is well-structured and front-loaded, starting with the core value proposition, then a clear list of use cases, and finishing with technical details. Each sentence earns its place; the bullet points make it scannable without excessive length.

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 provides sufficient context: it states the return shape ('top tools, top packs, and total call volume'), the data source, no PII, and caching behavior. No additional information seems necessary for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for the single `window` parameter, meaning the schema already explains the enum values and their trade-offs ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand.'). The description only reiterates the window options without adding new semantic details, 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: 'Returns the top tools, top packs, and total call volume' based on what 'other AI agents are calling on Pipeworx right now.' This specific verb+resource combination distinguishes it from sibling tools like discover_tools, as it focuses on real-time aggregate usage rather than general tool discovery.

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

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

The description provides 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.' While it gives clear context, it does not explicitly state when not to use this tool or name alternative tools, so it misses the full 'when-not' guidance.

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

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

Annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description adds substantial context: the semantic anchor similarity threshold (≥0.30 Jaccard), the placeholder filter, and the critical fill-check behavior that prevents trading on theoretical edges not present in the CLOB book.

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

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

Though lengthy, the description is densely informative and well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds meaningful detail, and the main purpose is front-loaded. The structure earns the length.

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

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

No output schema exists, so the description compensates by detailing response fields (opportunities[], partition_check, fill_check). It covers all important behavioral aspects: mode selection, filtering logic, response formats, and the caveat to avoid trading when fill_check shows zero realizable edge. This is complete for a tool of this 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% with clear descriptions, but the tool description goes further by explaining the semantic distinction between event and topic modes, providing concrete slug examples, and detailing how each mode processes the input (walks child markets vs. searches related events).

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'—a specific verb, resource, and method. It clearly distinguishes the tool's scope from siblings like polymarket_edge_tracker by focusing on arbitrage detection via consistency checks.

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

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

Provides explicit guidance on when to use each mode: 'event' for a specific known market, 'topic' for cross-event scanning. It recommends event mode for specific markets and explicitly points to polymarket_fill_risk for custom sizing, giving clear alternative tool usage.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing caching (1h at KV level), response diagnostics (_diagnostics), the unreliable Fed signal with rationale, and specific filtering behaviors (placeholder-slug filter, >20% placeholder partitions skipped). It also explains the 24h-move warning and why min_partition_leg_kelly behaves differently for partitions. 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 front-loaded with a clear purpose and uses recognizable sections (segments, knobs, response top-level). However, it is extremely verbose, including per-sport alpha coefficients (tennis 1.02, soccer 1.10, etc.) and detailed model-family acronyms that are not necessary for tool selection or invocation. It reads more like a spec sheet than a concise tool guide.

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

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

Given no output schema, the description comprehensively documents the response structure: by_segment, fed_candidates/fed_note, and _diagnostics with funnel counters. It also details per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.) and explains why segments might be empty. This is exceptional coverage for such a complex tool.

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

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

All 9 parameters have thorough schema descriptions (100% coverage), so the baseline is 3. The tool description adds extra meaning by grouping "TRADEABLE-EDGE KNOBS," explaining the relationship between min_partition_leg_kelly and basket trades, and noting that caching is keyed on all knobs—context not present in the schema alone.

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

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

The opening sentence states a specific verb and resource: "Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price." It further differentiates from siblings by framing it as "what should I bet on today" and by detailing three output segments (model_driven, structural_arbitrage, concentrated_longshot), which distinguishes it from tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear usage context: it is built for agents to discover betting opportunities without paging through hundreds of markets. It also explains how tradeable-edge knobs (min_liquidity, max_spread_pp) affect usability. However, it never explicitly states when to prefer this over sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it lacks an explicit 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?

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, but the description adds substantial behavioral context: history is bounded by a 60-day TTL, snapshots are written on cache-miss so gaps indicate no scan, decay is computed from daily closes not intraday, and edge_pp_net is signed with negative meaning SELL YES. This goes far beyond the annotations and helps the agent set expectations.

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

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

The description is long but extremely well structured with explicit 'Args:', 'RESPONSE:', and 'LIMITS:' sections. The opening sentence is a concise summary, and every subsequent sentence adds essential information about response fields, expiration semantics, and data limitations. No fluff or repetition.

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

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

Even though there is no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), what each element means, and how to interpret the data (median lifespan as competition clock, signed edge values). It also covers edge cases like TTL bounds and snapshot gaps, making the tool fully understandable and safe to invoke.

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

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

The input schema already provides full descriptions for both parameters (days with clamp 2-30 and default 14, window with enum 24hr | 1wk | 1mo and default 1wk). The description repeats these defaults and adds no new semantic detail beyond what the schema provides, so it earns the baseline 3 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 defines the tool as 'edge persistence and decay telemetry' built from daily polymarket_edges snapshots, answering a specific question about how long an edge has existed. It distinguishes itself from simpler edge tools like polymarket_edges by focusing on time-series persistence and decay, so an agent can easily tell when to use this over siblings.

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

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

The description states the intended use case: 'Answers how long has this edge existed and is it shrinking?' and explains why old wide edges are different from fresh ones. It implies it should be used when edge persistence matters, but it does not explicitly name alternatives like polymarket_edges or state when to use those instead, so it stops short of full exclusion guidance.

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

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

Annotations already cover read-only, non-destructive, and idempotent hints, and the description goes well beyond that by detailing how it walks the order book ladder, what it returns (top_of_book, vwap_fill_price, slippage_pp, verdict), and critical risk behaviors like partial basket fills leading to unhedged directional positions.

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 SINGLE-MARKET and BASKET sections. It is densely informative, and while it could be more streamlined, every sentence adds necessary context for a complex dual-mode tool.

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

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

With no output schema, the description enumerates key return fields (e.g., capture_ratio, thin_legs[], max_clean_notional_usd) and explains the risk profile. It also covers mode-specific behavior and the key risk warning, making it complete for an agent to understand the tool's capabilities and implications.

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 further clarifies the nuanced meaning of size_usd in basket mode ('settlement notional S — shares per leg') and explains the auto default for side, adding meaningful interpretation beyond the schema fields.

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 verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating it is the pre-trade risk check to use before acting on those signals.

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 mode selection (market vs event) and parameter requirements, effectively covering alternatives and prerequisites.

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 hints, but the description goes far beyond them: it details safety fields (compatibility_warning, compatibility_codes[]), explains that both can be non-empty even when matched_pairs>0, specifies that 'unknown' legs are NEVER paired and get routed to skipped_unclassified/low_confidence_pairs, and exposes counters like skipped_cross_type/cross_subtype. This is rich behavioral disclosure that materially changes how an agent should interpret results.

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

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

The description is long, but each sentence carries information: core purpose, signal caveat, two modes, response structure, safety fields, code semantics, pairing rules, alignment, and a reality-check warning. It front-loads the main concept and modes, then proceeds logically into edge cases. Slightly dense, but not bloated; no sentence is 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?

There is no output schema, so the description must carry the return-type burden — and it does: leg prices as 0-1 probabilities, matched spreads as Kalshi minus Polymarket in pp, compatibility fields with code meanings, temporal alignment, skipped-classification routing, and low-confidence inspection pairs. Edge cases and failure modes are covered in unusual depth, leaving an agent well-equipped to interpret and act on outputs.

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 by explaining the topic list in prose, clarifying that explicit tickers/slugs override the mapped side, and giving concrete examples (KXFED-26OCT, fed-decision-in-june-825). It stops short of documenting all parameter value formats exhaustively, but it does more than merely restate 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?

Opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' The verb-resource pair is unmistakable, and the description distinguishes it from sibling polymarket tools (e.g., polymarket_arbitrage, polymarket_edges) by focusing on cross-venue comparison of equivalent bets. The two explicit modes further sharpen what the tool does.

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

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

The description clearly explains when the spread is a real signal ('when the bet shapes are equivalent') and when it is not, and it enumerates both invocation modes (topic shortcuts vs explicit ticker/slug). It warns that 'pre-mapped ≠ tradeable' and that most topics return a compatibility warning today. However, it does not explicitly name alternatives among siblings (e.g., when to use polymarket_arbitrage instead), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about return values ('image URL and breed name') but does not disclose edge cases or non-obvious behavior. Given the annotation coverage, a score of 3 is appropriate.

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

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

The description is two sentences long, front-loaded with the core purpose, and every sentence earns its place. No wasted words or irrelevant detail.

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, read-only tool with rich annotations and an output schema, the description covers purpose, return value, and usage context. A minor gap is lack of explicit behavior for invalid breed names, but the schema's reference to list_breeds mitigates this.

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 only parameter 'breed' is fully documented in the schema with examples and a pointer to list_breeds. Schema description coverage is 100%, so the description does not need to compensate; it only adds redundant examples to 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 uses a specific verb and resource: 'Get one dog photo for a specific breed' with concrete examples. It clearly distinguishes itself from generic random_image and plural breed_images by emphasizing 'one photo' of a 'specific breed'.

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

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

The description explicitly states when to use the tool: 'Use when you need exactly one photo of a particular breed.' It does not explicitly name alternatives, but the context is clear and the sibling list includes likely 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by stating it returns an image URL and breed name, which goes beyond the annotations. Given the simplicity of the tool and the strong annotations, this is sufficient, though it could have mentioned the random selection behavior more explicitly.

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

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

The description is a single, front-loaded sentence that immediately states the action and result. Every word earns its place, with no unnecessary detail or filler. It is highly concise and well-structured.

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

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

Given the tool's low complexity, zero parameters, and rich annotations, the description is complete. It states the tool's purpose, usage context, and return value, which is all needed for an agent to select and invoke it correctly. The presence of an output schema further reduces the need to explain return details in the description.

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

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

The tool has zero parameters, so the schema provides complete coverage. According to the rubric, a baseline of 4 is appropriate for 0-parameter tools, and the description does not need to add parameter details. The description does not repeat parameter information, which would be redundant.

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

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

The description starts with a specific verb and resource ('Get a random dog photo') and clearly distinguishes itself from sibling tools like random_breed_image and breed_images by stating it returns any dog picture without breed preference. This fully clarifies its purpose and differentiates it from alternatives.

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

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

The description explicitly states when to use the tool ('Use when you need any dog picture without a specific breed preference'), providing clear context. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context about scoping to an identifier and the behavior of omitting the key (listing all), which is not present in annotations. 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?

Three sentences, each earning its place: the operation, the use case, and the ecosystem relationship. No redundancy or fluff.

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

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

For a simple one-parameter tool with full schema coverage and strong annotations, the description fully covers operation modes, scoping, and relationships to sibling tools. No output schema is needed for this read-only lookup.

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 description already states 'omit to list all keys.' The description enriches semantics by giving concrete examples of key values ('the user's target ticker, an address, prior research notes'), helping the agent understand the intended usage of the key parameter.

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

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

The description clearly states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from siblings by explicitly naming remember and forget, and specifies two distinct operation modes (retrieve by key or list all).

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 to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives/companion tools ('Pair with remember to save, forget to delete') and explains the scoping ('Scoped to your identifier').

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=true and idempotentHint=true, but the description says setting mark_read:true flags returned events as read 'so the next call only shows newer ones' — a state mutation that breaks idempotency. This is an explicit contradiction, so score is 1.

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 purpose, then return details, filters, and side-effect/alternative endpoint. Every clause adds information without 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?

Despite the contradiction, the description is rich: it describes the return payload, filtering options, the mark_read behavior, polling suitability, and an external endpoint for scripts. With no output schema, this covers the essential usage dimensions.

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

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

Schema already covers all five parameters at 100%. The description adds value by giving a concrete type example ('sec_8k'), clarifying the since parameter as ISO timestamp, and explaining mark_read's effect on subsequent calls. It doesn't need to restate limit or unread_only.

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 verb-object pair ('Pull fired events from your subscription feed') and specifies the return content (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on alert events rather than subscription management.

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 gives context that polling is supported and points to an alternative HTTP endpoint for scripts/dashboards, making the trade-off explicit. It doesn't spell out when not to use the tool (e.g., for managing subscriptions), but the purpose statement implicitly separates it from 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses fan-out to SEC EDGAR, GDELT→GNews with a specific fallback trigger (rate-limited or 5xx), and a soft-fail for USPTO due to API sunset. This gives the agent realistic expectations for data sourcing and failure modes.

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 tightly packed; the opening paraphrases quickly give way to a precise definition. Every sentence contributes source behavior, fallback logic, return shape, or an alternative tool. It is not overly verbose for the amount of useful operational detail it conveys.

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

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

Even without an output schema, the description explains the return structure (changes[] grouped by source, total_changes, citation URIs), external API dependencies, and a sibling alternative. This is complete enough for an agent to predict and interpret results effectively.

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 of parameters is 100%, so the baseline is 3. The description adds value by providing concrete examples for `since` (ISO date and relative shorthand), clarifying how each source uses the window, and reinforcing that `value` can be a ticker or CIK. This is modest enrichment over the schema, warranting a 4.

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

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

The description opens with a clear action verb and resource: 'change feed for a company in the last N days/weeks/months.' It provides multiple example user intents and explicitly distinguishes itself from the sibling entity_profile tool, making selection 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 states exactly when to use this tool versus an alternative: 'Use entity_profile instead when you want the static profile...' It also describes the GDELT→GNews fallback behavior and notes typical monitoring windows, giving an agent clear contextual guidance.

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

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

Annotations already convey idempotency, non-read-only, and non-destructive behavior. The description adds valuable context beyond these: memory is scoped by the agent's identifier, authenticated vs anonymous retention (24 hours), and the pairing with recall and forget. No contradictions with annotations.

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

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

Four concise sentences, each serving a purpose: action, usage trigger, storage semantics, and companion tools. No fluff or redundancy. The description is front-loaded with the core purpose and immediately gives actionable 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?

For a simple two-parameter tool with no output schema, the description is comprehensively complete. It covers what the tool does, when to use it, how storage works (key-value, scoping, persistence), and how it relates to recall and forget. 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% and already provides examples for key and value. The description mentions 'key-value pair' and gives examples of what to store (e.g., 'a resolved ticker') but does not add substantive parameter semantics beyond what the schema already documents. The baseline of 3 applies because the schema carries the full burden.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later.' It uses a specific verb ('save') and resource (data), and distinguishes itself from sibling tools by explicitly mentioning its complementary relationship with recall and forget, making its purpose unmistakable.

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

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

Provides clear guidance on when to use the tool: 'Use when you discover something worth carrying forward' with concrete examples like 'a resolved ticker, a target address, a user preference, a research subject.' It does not explicitly state when not to use it or name alternatives, but the context is strong enough to guide an agent effectively.

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, openWorldHint, and non-destructive. The description adds rich behavioral context: internal cascading through endpoints, graceful degradation (LEI/FIGI unavailable but EDGAR still returns), explicit unresolved identifiers, and source labeling. No contradiction with annotations.

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

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

Front-loaded with example queries and clear 'Use FIRST' directive. The description is relatively long but justified by the complexity (two entity types, multiple identifiers, sources, fallback). Could be slightly tightened without losing clarity.

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

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

Given no output schema, the description fully explains return values: CIK, ticker, company_name, LEI with ownership, FIGI, unresolved identifiers, source labels. Covers graceful degradation and cascading behavior. Thoroughly handles the complexity of the tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds substantial value: explains the enum types with examples (company vs. drug), provides detailed usage examples for value (ticker, CIK, ISIN, name, drug names), and explains special behavior like ISIN-to-LEI mapping. Goes well beyond the schema.

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

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

The description clearly states it resolves names to canonical/official identifiers, with specific example queries like 'what's the ticker' and 'find the CIK'. It distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID', implying it's the primary tool for entity resolution among siblings.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. However, it does not explicitly state when not to use it or name alternative sibling tools, leaving some ambiguity for the agent.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context by revealing that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score/confidence/signal density. This gives insight into the tool's internal process and output 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 four concise sentences, each adding value: purpose, mechanism, use case, and return summary. It front-loads the core functionality and avoids redundancy or 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?

With no output schema, the description adequately explains return values ('ranked list with score, confidence, signal density per entity') and covers the tool's composite behavior (using ai_visibility_check). Combined with full schema coverage and safe annotations, the description is 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%, meaning all parameter meanings are already documented. The description reinforces that entities are compared and that context is shared, but it does not add significant detail beyond what the schema provides. Therefore, baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side'. It specifies the verb (compare), resource (AI visibility), and scope (multiple entities), and distinguishes it from the sibling ai_visibility_check by emphasizing batched comparison and ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question, and implicitly contrasts with single-entity probing by saying 'across multiple entities side-by-side'. However, it does not explicitly state when NOT to use it or name alternative tools for other scenarios, though ai_visibility_check is mentioned as the underlying probe.

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 (read-only, open-world, idempotent), the description discloses composite behavior, partial failure degradation ('sources_failed will list it if it times out'), and potential latency ('bundlephobia's first measurement... can take 5-30s'). No contradiction with annotations.

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

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

The description is long but every sentence adds value. It is front-loaded with the core purpose, then usage, return fields, ecosystem scope, and error behavior. 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?

Even without an output schema, the description enumerates all return fields (is_latest, license, published_at, etc.), lists alternative versions, and explains fallback behavior for non-npm ecosystems. It is complete for a complex tool with multiple data sources.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema for the 'package' and 'version' parameters, though it implicitly relates version to defaulting to latest in the schema. No further clarification is provided in the description.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, bundle size, and tree-shaking. It uses a specific verb ('scan') and resource ('npm package'), and distinguishes itself from siblings by combining deps.dev and bundlephobia data in one call.

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 an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clearly indicating when not to use 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?

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses return format (top-N passages with character offsets and similarity scores), algorithm details (BGE-base-en embeddings, cosine similarity, 500-char windows), and truncation behavior (longer inputs truncated and flagged). This is far more than the annotations alone.

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 that front-loads the core purpose ('Semantic search INSIDE a fetched record'). Every clause contributes: usage scenario, benefit, output details, algorithm, constraints, and pairing with another tool. No filler.

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

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

For a 3-parameter tool with no output schema, this description is complete. It explains the purpose, when to use it, what it returns, its constraints (200K char cap), and how it relates to sibling tools. An agent has all the information needed 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 coverage is 100%, so the baseline is 3. The description adds value by giving query examples ('supply-chain risk', 'drug interactions with warfarin') and contextualizing the 'text' parameter as 'a fetched record'. It also explains why offsets are important for verification, which is not in the schema.

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

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

The description states a specific verb ('Semantic search') and a specific resource ('a fetched record'), and distinguishes it from siblings by emphasizing it operates on already-pulled text. It also explicitly pairs with ask_pipeworx_grounded, clarifying its unique role in the workflow.

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

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

It gives an explicit use case: 'Use when the record is too big to cram into the prompt'. It also names an alternative/complementary tool (ask_pipeworx_grounded) and mentions the 200K character cap, which tells the agent when not to use it (e.g., for very large inputs).

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: account requirement, return value, phone verification, SMS caps, and the persistent feed mechanism. It does not contradict annotations, though it omits webhook delivery from the main text (details are only in the schema).

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

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

The description is dense but well-structured: it starts with the core purpose, then return value, prerequisites, types, and delivery options. Every sentence carries useful information, though it could be slightly better organized with bullets.

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 options, the description covers most critical aspects: purpose, requirements, types, delivery channels, and return value. Minor gaps exist (webhook not mentioned in the description text, not all five types enumerated), but the schema fills these.

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 semantic value beyond the schema by explaining item code meanings (e.g., '5.02' = officer change) and giving concrete examples for sec_8k, polymarket_edge, and fred_series. This justifies a bump above the baseline of 3.

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

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

The description clearly states the verb 'Create' with the resource 'proactive monitoring subscription' to a live-data event stream, and explicitly notes it returns the new subscription ID. This distinguishes it from siblings like list_subscriptions and unsubscribe, which are about listing and removing subscriptions.

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

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

The description provides practical usage context: it requires a Pipeworx OAuth account, lists supported types with examples, and explains delivery channels including how to pull from the always-on feed via recent_alerts. However, it does not explicitly state when not to use the tool or name alternative tools for comparison.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it returns category-bucketed examples drawn from the live catalog and includes the exact tool+argument shape. It does not contradict annotations and goes beyond them by revealing output composition and the 'use first' role. It could mention edge cases (e.g., invalid topic) but the core behavior is well disclosed.

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

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

The description is front-loaded with example user intents, then quickly establishes the purpose, output, and usage. Every sentence earns its place: it covers categories, tool shapes, argument behavior, and sibling alternatives. Despite its length, it is dense and well-structured, making it easy to scan for an agent.

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

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

With only one optional parameter and no output schema, the description fully compensates by explaining the return value (category-bucketed example questions with tool+argument shape) and the use case (onboarding, learning meta-tools). It also gives ordering guidance ('Use this FIRST'), making it complete for an agent to decide when and how to invoke.

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

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

The input schema already provides a comprehensive description of the optional `topic` parameter, listing all valid values and the omit behavior. The description adds little beyond the schema: it repeats examples like 'finance', 'pharma', 'betting' and the focus concept. Since schema coverage is 100%, the baseline is 3, and the description does not meaningfully compensate with extra semantic details.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses specific verbs like 'Returns' and 'Call' and distinguishes itself from siblings by positioning itself as the first step, even listing related meta-tools.

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

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

The description provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the argument behavior (no args for full spread, pass topic to focus) and names alternatives like ask_pipeworx, entity_profile, compare_entities, giving clear when and when-not guidance.

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

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

Beyond the annotations (readOnly=true, destructiveHint=false, idempotentHint=true), the description adds critical behavioral detail: ownership enforcement, and that the row is deactivated rather than deleted so historical events remain available via recent_alerts. This significantly clarifies the tool's side effects without contradicting any 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 sentences, front-loaded with the action, and every sentence delivers essential information. There is no fluff or redundancy; the description is perfectly sized for a simple tool.

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

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

For a single-parameter mutation tool with good annotations and no output schema, the description is fully complete: it explains the action, the ownership restriction, the non-destructive behavior, and the relationship to recent_alerts. No critical information 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?

The schema already provides 100% coverage for the single parameter 'id' with a clear description ('Subscription id (uuid) returned by subscribe'). The tool description does not add additional parameter-level meaning beyond restating 'by id', so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and object: 'Cancel a subscription by id.' It clearly identifies the resource (subscription) and the operation (cancel), and its naming aligns with the sibling tools 'subscribe' and 'list_subscriptions', 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?

The description implies the tool is for canceling subscriptions and notes a key constraint ('Ownership is enforced — you can only cancel your own subscriptions'), which guides appropriate usage. It does not explicitly name alternatives or exclusions, but the purpose is clear enough in the context of 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?

With annotations already declaring read-only and non-destructive behavior, the description adds substantial behavioral context: the dual-path verification logic (SEC EDGAR vs. grounded pipeline), the semantic distinction between 'could_not_verify' and 'unsupported', the presence of verification_error{stage,detail}, and explicit caller warnings not to treat failures as evidence. This goes well 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 well-structured: it opens with user intent phrases, states the core use case, explains the routing, lists return values, and highlights a critical caller caveat. Each sentence contributes necessary information, though it is denser than strictly needed and could be tightened without losing value.

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

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

Given no output schema, the description fully covers the return verdicts, citation format, and error semantics. It explains the two paths, the failure modes, and the efficiency improvement over multiple sequential calls. This makes the tool self-contained and complete 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 coverage is 100% for both parameters, so the schema already documents them. The description adds extra guidance for tolerance_pct (overrides implied wording, recommended 1–2 for hallucination detection) and clarifies the default behavior, which enriches the parameter meaning beyond the schema descriptions.

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

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

The description clearly defines the tool as a natural-language claim verification service with specific use-case phrases ('Is it true that…', 'fact check', 'verify the claim that…'). It distinguishes itself from generic Q&A siblings like ask_pipeworx by focusing on factual verification against authoritative sources, and it specifies the return verdict types.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use guidance. It also explains the two internal routing paths and mentions efficiency gains, but it does not explicitly name alternative tools or state when not to use this tool beyond that context.

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