nouel

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds meaningful behavioral context beyond that: default free model, BYO key for Anthropic (with direct cost implication), and the exact return shape per model. This is rich, non-redundant disclosure.

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

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

Three sentences, zero filler. The purpose is front-loaded, followed by default behavior, return format, and use cases. Every sentence carries information.

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

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

Despite having no output schema, the description compensates by specifying per-model {score, confidence, signals, raw_response} plus a combined view. It also covers model selection, cost, and practical use cases, making the tool's behavior fully comprehensible for selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces that `_apiKey` enables Anthropic probing and that the default model is Workers AI, but it does not add meaning beyond the schema's own parameter descriptions. No deduction or bonus.

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 action ('Probe one or more LLMs') with a clear resource and measurable output ('score visibility (0-100) per model'). It also names concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) that differentiate it from sibling tools like ask_pipeworx or deep_research.

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

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

The description gives clear when-to-use guidance via use cases, but does not explicitly discuss when not to use the tool or name alternative tools. This is 'clear context, no exclusions,' so a 4 fits.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety behavior is covered. The description adds valuable behavioral context by explaining that the tool routes to one of 5,718 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs, which is useful 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 front-loaded with the key instruction to prefer this over web search and includes concrete trigger phrases and examples that make the intended use vivid. It is longer than strictly necessary, but nearly every sentence adds practical guidance, so the length is justified.

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

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

The description covers what the tool does, when to use it, how it behaves internally, and what kind of output to expect. Given the annotations already cover safety and idempotency, and the input schema is fully documented, the only minor gap is the lack of more specific sibling routing guidance, but overall it is fairly complete for such a broad router 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 schema already documents each parameter as an alias for the natural-language question. The description adds examples and phrasing patterns, but it does not meaningfully extend the parameter semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific function: routing a natural-language question to one of many tools and returning a structured, cited answer. It distinguishes itself from web search and names examples, but it does not explicitly differentiate from the sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, only offering a generic 'start here' heuristic.

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 strong when-to-use guidance: prefer over web search, use for factual/real-world questions, and use whenever trigger phrases like 'look up', 'find', or 'latest' appear. It also gives an exclusion ('except when another tool is clearly better targeted'), but it does not name specific sibling tools or describe concrete scenarios where one of them should be selected instead.

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

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

The annotations already indicate a read-only, idempotent, non-destructive operation, so the bar for description value is lower. The description adds genuinely useful behavioral context beyond those annotations: it is a live experimental edge router, candidate improvements are enabled whenever under test, none are currently active, and it is a full working router rather than a partial fallback. It clearly explains the current state and potential future variation without contradicting the annotations.

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

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

The description is somewhat detailed, listing 5,718 tools and the 2026-07-26 retirement date, but every sentence contributes to the core point that this is a live beta clone of ask_pipeworx. It is front-loaded with the essential identity and then supplements with current status and usage guidance. A slightly shorter version would be possible, but the structure is efficient and purposeful.

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 that the tool is a beta variant of a sibling, the description adequately covers the current state, the relationship to ask_pipeworx, and the fact that it is fully functional. Since there is no output schema, the callback to ask_pipeworx's same response shape provides enough return-value guidance. The description could mention what kind of questions the router handles, but the universal-router framing makes that reasonably inferable.

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

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

Schema description coverage is 100%, so the schema already documents the parameters and their aliases. The description does not add per-parameter semantic detail, only the general statement that it uses the same arguments as ask_pipeworx, which is useful context but not a substitute for parameter-level meaning.

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 the resource (ask_pipeworx) and the verb (ask) while making clear this is the beta variant of the same universal router. It identifies the tool as a full working router with identical tools, arguments, and response shape, which distinguishes it from the stable ask_pipeworx and ask_pipeworx_grounded siblings. It could be more explicit about what the question parameter is used for, but the core purpose is clear.

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

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

The description explicitly tells the agent to use it exactly like ask_pipeworx when wanting the newest routing, and explains that the current behavior matches the stable router exactly because no candidate is active. This gives a clear condition for choosing it over the stable sibling, though it does not explicitly say when to avoid using it.

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

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

Annotations already declare a safe read-only, idempotent, open-world operation, so the bar is lower — yet the description adds substantial behavioral context: the exact success return shape, the refusal contract with all five refusal_reason enum values, the guarantee that extraction uses only tool-result content, and the cost of one extra LLM call. This exceeds what annotations provide and fully discloses the tool's refusal 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?

Dense but zero-waste prose: every sentence carries load — purpose, routing scope, extraction guarantee, success/refusal return contracts, use cases, and cost tradeoff. The core concept is front-loaded ('Hallucination-resistant answer mode for high-stakes reads'), and the return/refusal contracts are compactly encoded rather than repeated from structured fields.

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

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

Since there is no output schema, the description correctly carries the full burden of explaining return values (answer, evidence, confidence, source, fetched_at, refusal_reason) and the failure mode (refusal with categorized reasons). Combined with 100% schema param coverage and safety-bearing annotations, nothing an agent needs to invoke or interpret this tool correctly 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 description coverage is 100%, so the baseline is 3 even if the description adds no parameter detail. The description does not explain the mode/question parameters further — it leaves that to the schema. It indirectly informs 'mode' by explaining when grounded mode matters, but it adds no format, alias, or value-level semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific, differentiating statement: 'Hallucination-resistant answer mode for high-stakes reads.' It names the resource (Pipeworx routing across 5,718 tools/1496 sources), a distinct behavior (extract answer using ONLY tool-result content), and explicitly positions itself against the sibling 'same routing as ask_pipeworx.' An agent can immediately distinguish this from ask_pipeworx and ask_pipeworx_beta without opening 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups,' including the cost reason ('Costs one extra LLM call'). This is model usage guidance with a named alternative.

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

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

The description goes far beyond the readOnlyHint annotation by disclosing fan-out behavior, resolver contract, parent_event extraction, NEWS fallback mechanisms, safety short-circuit statuses, and cancellation-rule parsing. It even quantifies response sizes and warns about blocking routes, providing rich behavioral context not inferable from annotations or 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 long but exceptionally well-structured, with a clear first sentence stating purpose and subsequent sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) making navigation easy. Every sentence contributes operational detail, though some redundancy exists (e.g., market input syntax repeated from schema) and the overall length is substantial.

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

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

Given the absence of an output schema, the description compensates by thoroughly covering return shapes (market, analysis, evidence), resolver confidence and alternatives, parent_event partition data, news fallback fields, safety statuses, and cancellation-rule risk. This is a complete operational picture for a complex tool, enabling an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, with the market parameter fully explained in the schema itself. The description reiterates the slug/URL/question-text formats but adds no new parameter semantics beyond what the schema already provides. Depth and include_raw are also fully documented in the schema, so the description adds no additional value here.

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

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

The description opens with a specific verb+resource: "Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call." It further distinguishes the tool by describing the fan-out to category-specific data packs and returning an evidence packet plus market-vs-model comparison, clearly separating it from siblings like validate_claim or polymarket_edges.

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

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

Explicit use cases are given: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." The description also offers conditional guidance like inspecting resolver fields before trusting analysis and checking cancellation rules before sizing. However, it does not explicitly name alternative tools or when not to use this tool, 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?

While annotations already mark readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and the return format with citation URIs. This goes 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 dense but efficiently front-loaded with trigger phrases and the core action. Some redundancy exists between 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups,' but overall the structure is logical and every 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 tool with no output schema, this description is remarkably complete: it explains inputs, entity-type-specific behavior, data provenance, ordering, and return artifacts. The note about off-calendar fiscal years and the comparison efficiency claim add context that fully prepares an agent to invoke the tool correctly.

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

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

The schema already covers both parameters with 100% description coverage, including an enum for type and min/max constraints for values. The description adds meaning by mapping type to specific data pulled (10-K financials vs. FAERS counts/trials) and providing concrete examples like ['AAPL','MSFT'] and ['ozempic','mounjaro'], which enhances parameter understanding.

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

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

The description opens with concrete trigger phrases and states exactly what the tool does: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sequential single-pack lookups and sibling tools like entity_profile by emphasizing parallel comparison of multiple entities.

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 triggers ('X vs Y', 'which is bigger', 'rank these companies') and says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' However, it does not name a specific alternative tool (e.g., entity_profile), so the guidance stops short of fully explicit 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=true and idempotentHint=true, the description still adds substantial behavioral context: auth/plan requirements, disambiguation from open-web search, the findings-packet structure (verbatim evidence, confidence, source, fetched_at, stable citation), explicit gaps[] for unanswered facets, 'never invented', contradictions[] for standard/thorough, hop field, citation_uri resolvability, semantic excerpting, and 15-90s latency. Nothing 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 description is long but every sentence earns its place: auth/alternative up front, then core mechanism, output format, depth semantics, and latency. It is well-structured and front-loaded, with only minor redundancy against the schema's depth description.

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

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

This is a complex research-orchestration tool with no output schema, so the description must fully explain return values and behavior. It does: findings packet contents, gaps[], contradictions[], hop field, citation_uri, semantic excerpting, latency expectations, and auth prerequisites. An agent can correctly invoke it and interpret its results without further 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 description coverage is 100%, so per the rubric baseline is 3. The description adds a little nuance beyond the schema ('Broad/multi-part is fine — decomposition is the point' for question, and depth-behavior details around hops and contradictions), but it mostly restates what the schema already documents for depth and doesn't substantially add meaning.

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 and resource: 'Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources' and details the mechanism ('Decomposes your question into focused facets, routes each to the right one of 5,718 tools IN PARALLEL, and returns a findings packet'). It also distinguishes itself from open-web search and from ask_pipeworx, so an agent can clearly tell it apart from siblings.

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

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

Explicit when-to-use and alternative guidance: 'If you are not signed in, use ask_pipeworx instead — it works on every tier' and 'Best for broad/multi-part questions over structured data... For a single lookup use ask_pipeworx.' It also explains the paid-plan condition for thorough depth, leaving no ambiguity about prerequisites or choice.

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

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

Annotations already mark it read-only and idempotent; the description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond safety hints. No contradictions with 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?

Three concise sentences cover purpose, usage context, and return value. The description is front-loaded with the core action ('Find tools'), and every sentence adds substantive 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?

The description covers what it does, when to use it, what it returns, and the scope of domains. With no output schema, it still explains the return structure (top-N tools with names, descriptions, and full input schemas) sufficiently for an agent to invoke and use results.

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

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

Schema coverage is 100% with descriptions for query, limit, and multiple aliases. The description reinforces the natural-language query behavior and lists example queries, but adds no parameter-specific details beyond the schema, so baseline 3 is appropriate.

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

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

Description opens with 'Find tools by describing the data or task,' clearly identifying the verb (find) and resource (tools). It distinguishes itself from sibling tools by being the only tool-discovery meta-tool, and the listed domains (SEC filings, FDA drugs, etc.) further scope its purpose.

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

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

Explicitly states '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.' This gives clear when-to-use guidance without needing to infer context.

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

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

Beyond the readOnly/idempotent annotations, it discloses fan-out behavior across multiple APIs, the return structure, and two failure/fallback behaviors: patents 'soft-fails until reactivated' after USPTO sunset, and news uses 'GDELT→GNews fallback.' It also states that names are not supported, preventing false expectations.

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

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

The description is dense but well-organized: examples first, then purpose, usage guideline, return details, and parameter format. Every sentence contributes critical information—no filler—and the structure front-loads the most important usage 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?

There is no output schema, but the description enumerates all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), making the tool's output fully self-describing. It also covers input constraints, usage context, and behavioral nuances, making it complete for an agent.

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

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

Schema coverage is 100%, and the description repeats the value format (ticker or zero-padded CIK) but adds no substantive new meaning beyond the schema. It does provide concrete examples ('AAPL', '0000320193') and the 'names not supported' constraint, but these are also present in the schema. Baseline 3 applies because the schema fully describes the parameters.

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

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

The description opens with multiple natural-language examples and immediately defines the tool as 'full cross-source profile of a US public company in ONE parallel call.' It explicitly lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and the returned fields, clearly distinguishing it from single-source lookups like the sibling SEC/news 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?

It provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives an exclusion for name inputs with a clear alternative: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the core safety profile. The description adds usage scenarios but does not introduce additional behavioral traits (e.g., irreversibility, behavior on missing keys). It does not contradict annotations, but the added value beyond them is limited.

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 concise sentences, each earning its place: the action, the conditions for use, and the relationship to related tools. The description is front-loaded with the core verb and has no unnecessary 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 one parameter, no output schema, and strong annotations, the description covers purpose, usage, and sibling relationships. A minor gap is the lack of explicit statement about behavior when the key doesn't exist, but the idempotentHint annotation implies it is safe. Overall, it is adequately complete for a simple deletion tool.

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

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

The single 'key' parameter is fully documented in the schema with 'Memory key to delete' at 100% coverage. The description reuses the term 'key' but adds no format, constraints, or examples beyond the schema, so the baseline of 3 applies.

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

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

The description uses the specific verb 'Delete' with the resource 'previously stored memory by key', clearly distinguishing it from the sibling tools remember and recall. The title 'Forget' aligns semantically, and the description leaves no ambiguity about the tool's function.

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

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

Explicitly states when to use ('context is stale, task done, sensitive data') and instructs pairing with remember and recall, providing clear context and pointing to alternatives. For a memory deletion tool, this is sufficient guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, covering the safety profile. The description adds behavioral detail — that it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown — which is not visible in annotations. Minor gap: no mention of edge cases like unreachable URLs.

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-loaded: it states the core purpose first, then the process, output format, and use cases. Each sentence adds distinct 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?

With only two simple parameters and no output schema, the description adequately covers purpose, process, output, and usage scenarios. It could mention failure handling (e.g., what if a URL is unreachable), but overall it is nearly 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?

The input schema provides 100% coverage for both parameters (url and max_links) with clear descriptions. The tool description's references to 'key links' and 'standard llms.txt format' offer only mild additional context for max_links, 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 'Generate a production-ready llms.txt file for any URL', a specific verb, resource, and scope. It clearly states the tool's purpose and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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

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

The 'Useful for' list specifies three concrete scenarios: getting a client's site indexed, drafting for one's own project, and auditing a competitor. This gives clear context for when to use the tool, 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 establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context, such as the optional category filter and the return payload, without contradicting the annotations.

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

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

The description is two sentences with no filler: a clear functional statement and a return-value note. It is front-loaded and information-dense.

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

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

Given the simple tool (2 params, 1 required), full schema coverage, annotations for safety, and an output schema, the description sufficiently covers purpose, parameters, and returns. No critical information is missing for correct use.

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

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

The input schema provides complete descriptions for both parameters, including the year constraint and valid category codes. The description only echoes the optional filtering without adding new semantic details, matching the baseline for full schema coverage.

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

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

The description clearly states the tool's function: 'Get all Nobel Prizes awarded in a specific year' with optional category filtering, and specifies the return fields: 'laureate names, categories, and citations'. This specific verb+resource+scope distinguishes it from sibling tools like search_laureates.

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 its use case: when you need prizes for a specific year, optionally filtered by category. However, it does not explicitly mention when not to use it or name alternatives like search_laureates, so it falls short of a perfect 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 safety is covered. The description adds valuable context by scoping to the caller's subscriptions and disclosing the exact return fields (id, type, params, created_at, etc.). This goes beyond the annotations and helps the agent predict output structure.

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 with no filler. The first sentence states the purpose and return fields; the second gives actionable usage guidance. Every word earns its place.

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

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

Despite having no output schema, the description lists all return fields, so the agent knows exactly what to expect. The single optional parameter is fully documented in the schema. The use case is clearly tied to sibling operations (subscribe/unsubscribe), making this complete for a simple list 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?

There is one optional parameter (include_inactive) with a clear English description in the schema covering 100% of parameters. The tool description does not mention this parameter, but it's consistent with the phrase 'active subscriptions' (implying inactive excluded by default). The schema does the heavy lifting, 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 uses a specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions'. It differentiates from sibling tools like subscribe/unsubscribe by focusing on listing existing subscriptions. Including the return fields adds further clarity.

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

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

The description explicitly states when to use this tool: 'before adding more' or 'to find an id to cancel', which implies alternatives (subscribe/unsubscribe). This gives the agent clear contextual guidance on when this list tool is appropriate versus modifying 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?

Despite annotations being all false, the description discloses meaningful behaviors: rate-limiting ("Rate-limited to 5 per identifier per day"), no account needed to file, the claim_token round-trip workflow, and that feedback is free and does not count against quota. It also clarifies that the team reads digests daily and that signal affects the roadmap—context annotations cannot convey.

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

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

The description is a dense paragraph but is well front-loaded with the core purpose first and then usage boundaries. Every sentence adds necessary context, yet it is longer than strictly necessary and could be tightened with bullet-like structure or shorter clauses without losing meaning.

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

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

Given four parameters, nested context objects, no output schema, and no annotation support, the description is remarkably complete. It covers what happens when filing without an account, how to check resolution status, rate limits, scope restrictions, and content guidance—leaving little ambiguity for an agent deciding whether and how to call this tool.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the claim_token lifecycle ("pass it back later as pipeworx_feedback({claim_token:\"pwfb_…\"}) to read whether it was fixed and what changed") and mapping type categories to real scenarios like bug, feature, and data_gap. It adds value beyond the schema, though it does not need to restate all field descriptions.

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

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

The description opens with a specific verb+resource: "Tell the Pipeworx team something is broken, missing, or needs to exist." It clearly distinguishes this feedback tool from the many research/query siblings by stating its role is reporting issues to the Pipeworx team, not performing data 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?

The description gives explicit when-to-use guidance: "Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)." It also provides a strong exclusion: tools from different MCP servers should be filed elsewhere, and even tells users how to disambiguate Pipeworx tools.

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

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

Beyond the readOnly and idempotent hints, the description adds key behavioral context: it is 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and is 'Cached 5min-1h depending on window.' This discloses data provenance, privacy, and caching behavior, which is valuable for an agent deciding whether to trust/call the 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 about four sentences with a clear front-loaded purpose, followed by a compact numbered list of use cases. Every sentence earns its place, covering return values, use cases, data source, privacy, and caching without 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 tool with one optional parameter and no output schema, the description covers the return value ('top tools, top packs, and total call volume'), the shape ('(pack, tool, count)'), caching, and use-case context. It is sufficiently complete for an agent to invoke correctly.

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

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

The only parameter 'window' is fully described in the schema with enum values and semantics ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description adds nothing beyond that, so the schema does the heavy lifting and a baseline 3 is appropriate.

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

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

The description opens with 'What other AI agents are calling on Pipeworx right now' and explicitly states it 'Returns the top tools, top packs, and total call volume over a recent window', making the verb+resource clear. This distinguishes it from sibling tools like discover_tools by focusing on live usage trends rather than static discovery.

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

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

The description provides three explicit 'Useful for' scenarios, giving clear guidance on when to use the tool. However, it does not mention alternatives or exclusions, such as how it differs from discover_tools or when not to use it, so it stops short of full differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by explaining the Jaccard similarity threshold, placeholder filtering, the fill-check against live CLOB depth, and the condition 'realizable_edge_pp ≤ 0 means ... do not trade it.' This adds substantial behavioral context without contradicting annotations.

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

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

The description is long but well organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds necessary detail for a complex tool, and the main purpose is front-loaded. It is not bloated; the structure aids comprehension.

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

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

Despite lacking an output schema, the description fully specifies the response shape (opportunities[] with fields, partition_check details), covers all modes, filters, fill-check caveats, and even notes skipped_low_similarity output. For a tool with this complexity, the description is remarkably complete.

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

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

Schema coverage is 100% with descriptions for both event and topic. The tool description adds valuable semantics with example slugs, explanation of each mode's behavior, and the distinction between single-event and cross-event scanning, going beyond a bare repackaging of the schema.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (trending_scan, event, topic) and even references sibling tools like polymarket_fill_risk, making the tool's unique role 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?

Explicit guidance is provided: when to call with no args, when to pass event, when to pass topic, with concrete examples. It also explains the advantage of cross-event mode over single-event and points to a sibling tool for custom sizing, giving clear when-to-use and when-not-to-use signals.

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

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

The description goes far beyond annotations, disclosing response segments (by_segment), diagnostics funnel counters, the 24h-move warning, per-sport alpha values, placeholder-slug filters, Fed-bet exclusion rationale, and KV caching keyed on all knobs. It also explains that partition arbs return parent-level kelly=0 and are unaffected by min_kelly. This is a model of 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 a dense single paragraph with no headings or bullet points, making it hard to scan despite being front-loaded with the core purpose. Every sentence carries useful detail, but the sheer length and lack of structural breaks reduce readability and token efficiency for an AI agent.

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

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

With no output schema, the description bears full responsibility for explaining return values, and it delivers: it details the top-level by_segment structure, fed_candidates/fed_note, _diagnostics with funnel counters, and per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, 24h warning). It also covers caching behavior and knob interactions, making it complete for a complex tool.

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

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

All 9 parameters have schema descriptions, so the baseline is 3. The description adds valuable interaction semantics: min_liquidity/max_spread_pp are 'tradeable-edge filters', min_partition_leg_kelly applies to per-leg Kelly because min_kelly does not filter partitions, and slippage_pp is subtracted before ranking. This adds meaning beyond the schema, so a 4 is warranted.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly frames the tool for a single use case ('what should I bet on today') and distinguishes it from generic market data tools by emphasizing Pipeworx data disagreement.

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

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

The description explicitly states its intended use ('what should I bet on today') and gives a clear context for when to apply it: agents discover opportunities without paging hundreds of markets. It also explains filters like min_liquidity/max_spread_pp that refine use cases, but it does not explicitly compare to sibling tools (e.g., polymarket_arbitrage) or state when to avoid this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: the response structure (tracked, expired, snapshot_dates), the meaning of snapshot gaps, the 60-day TTL bound on history, and the decay calculation basis (daily closes, net of slippage). No contradictions found.

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

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

The description is longer than minimal but well-structured with sections for args, response, and limits. Every sentence provides distinct value, and key points are front-loaded. The response section is dense but organized, though slightly verbose in enumerating every field.

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 tool has a complex output (time-series telemetry) and no output schema, so the description carries the full burden of explaining return values. It thoroughly covers tracked, expired, snapshot_dates, and limitations (TTL, decay calculation, data gaps). This is comprehensive enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, and the description mostly echoes schema content: days default/clamp and window default. It adds the concept of 'snapshot family' for window and clarifies days as lookback, but does not meaningfully expand beyond the structured definitions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific analytical question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools by focusing on historical time-series rather than current edges.

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

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

The description provides concrete usage context with the example 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains the median lifespan as 'your competition clock.' However, it lacks explicit when-not-to-use guidance or direct comparisons to sibling tools like polymarket_edges, though it implies the relationship by stating it is built from polymarket_edges snapshots.

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

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

Beyond the readOnlyHint, idempotentHint, and non-destructive annotations, the description reveals detailed behavior: it 'walks the ladder', returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and identifies thin_legs and forced_directional_risk. It also warns about partial-fill dangers, which is critical behavioral context not captured by 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 densely packed with essential information: modes, parameters, outputs, and usage. It is front-loaded with the core purpose, then logically expands into requirements and details. While lengthy, every section serves a purpose, and the structure (SINGLE-MARKET vs BASKET) aids navigation.

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

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

For a complex tool with no output schema, the description enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk) and explains the risk context. It fully covers modes, parameters, and behavioral outcomes, making the tool well-specified.

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

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

The schema already covers all parameters at 100% (baseline 3). The description adds contextual meaning by clarifying that exactly one of market or event is required, how size_usd is interpreted differently in single-market vs basket mode, and that values are clamped 10–1,000,000. This improves parameter understanding beyond the raw schema.

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

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

The description clearly identifies the tool's function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk rather than edge detection.

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 given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why: theoretical overround on thin books is not capturable, and partial basket fills create unhedged directional risk. This provides clear when-to-use context and names the alternative tools.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description goes far beyond them: it discloses compatibility_warning and compatibility_codes semantics, unclassified legs are never paired, skipped counters, temporal_alignment, and that both safety fields can be non-empty even when matched_pairs>0. It also explains codes like event_subject_mismatch and non_equivalent_bet_shapes, making behavior predictable.

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 section earns its place: purpose, modes, response shape, safety fields, codes, and operational caveats. It is front-loaded with the core concept and uses explicit labels like TWO MODES, RESPONSE, and SAFETY FIELDS to keep dense information navigable; there is no filler.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It documents the returned fields (leg prices, top_spreads_pp, compatibility fields, skipped_unclassified, low_confidence_pairs, temporal_alignment, skipped counters) and explains edge cases such as unknown metric types and unverified premapped pairings.

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 each parameter already has a description, so baseline is 3. The description adds useful structural meaning beyond the schema: it frames topic as a pre-mapped auto-fetch mechanism, explicit ticker/slug as overriding the mapped side, and explains how the two modes interact with the matching logic.

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+resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes its scope from sibling tools by emphasizing cross-venue comparison, two invocation modes, and the 'same outcome on both sides' matching behavior.

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 clear context for when to use the tool: to compare equivalent bets across two venues, with two explicit modes (topic shortcuts vs explicit ticker/slug). It warns that pre-mapped topics often return compatibility_warning and 'pre-mapped ≠ tradeable', though it doesn't name specific sibling alternatives or state outright when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by revealing scoping per identifier (anonymous IP, BYO key hash, account ID) and the lifecycle with remember/forget. 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 concise at about 70 words, front-loading the core action and then providing usage context, scope, and paired tools. There is minor redundancy ('previously saved via remember' and 'stored earlier'), but overall every sentence contributes meaning.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description adequately covers purpose, usage scenario, scoping, and workflow. It omits only minor details like behavior when a key is not found, which are not critical for operation.

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

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

The input schema already documents the 'key' parameter with 100% coverage, so the baseline is 3. The description adds real-world examples of key types (ticker, address, notes) and clarifies the omit-key behavior, providing extra semantic context that helps an agent understand how to invoke the tool.

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

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

The description clearly states the tool retrieves previously saved values or lists all saved keys, using specific verbs and resource nouns. It distinguishes itself from sibling tools by explicitly pairing with remember and forget, and by describing the unique 'list all keys' behavior.

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

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

The description provides clear context for when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch'). It also mentions pairing with remember and forget, but does not explicitly exclude alternative tools like search_within. This is clear but lacks direct '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 declare readOnlyHint=true, but the description discloses a subtle side effect: setting mark_read:true flags events as read and affects the next call's results. This adds context beyond annotations. It also mentions the persisted feed and provides the HTTP endpoint, but does not cover auth requirements or rate limits.

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

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

The description is four sentences, each serving a purpose: main action, return payload, filtering/mark_read, and alternative endpoint. It is front-loaded with the core purpose and keeps details concise. A slight deduction for mixing filtering and external endpoint details into one long sentence, but overall efficient.

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 covers return values (source, citation_uri, raw payload). It also explains filtering, mark_read, and polling behavior. Missing some context on unread_only and potential parameter interactions, but the schema covers those. This is a well-rounded description for a 5-parameter optional tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the parameters by giving an example filter type ('sec_8k'), clarifying the 'since' parameter as an ISO timestamp, and explaining the effect of mark_read:true. It does not mention limit or unread_only, but these are well-documented 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 opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly states what the tool returns (recent alerts with source, citation_uri, raw payload). It is distinct from sibling names like list_subscriptions or recent_changes by focusing on fired alerts from a persisted feed.

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

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

The description gives clear context on when to use this tool (pulling alerts, filtering, marking read) and even mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools such as list_subscriptions or recent_changes, so alternatives among the tool list are not named.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses important behavioral traits: the GDELT→GNews fallback with specific failure conditions, the USPTO PatentsView API sunset causing soft-fail, and the output format including citation URIs. This adds substantial operational context.

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

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

The description is dense but well-structured, front-loading user-intent examples and then covering sources, fallbacks, parameter formats, output shape, and alternatives in a single flowing paragraph. Every clause contributes new information; there is no padding or redundancy.

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

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

Given the tool's complexity—three data sources, fallback logic, failure modes, and citation URIs—the description covers all essential aspects: what is returned, how sources behave, what inputs are valid, and when to choose another tool. With no output schema, this level of detail is sufficient for effective use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that 'value' accepts zero-padded CIKs, that the call fans out in parallel, and recommends typical monitoring intervals. It doesn't fully reinvent parameter docs but does add useful nuance.

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

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

The description clearly establishes the tool as a change-feed for a company, with direct query phrasings ('What's new with X', 'updates on Acme') and explicit data sources (SEC, GDELT/GNews, USPTO). It also distinguishes itself from entity_profile by noting that tool is for static profiles, not windowed changes.

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

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

It provides explicit usage context through user-intent examples, recommends a typical 'since' value ('Use "30d" or "1m" for typical monitoring'), and explicitly names the alternative tool (entity_profile) for static profile needs. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare idempotency and non-destructiveness. The description adds valuable context beyond annotations: memory scoping by identifier, persistence differences for authenticated vs. anonymous sessions (24-hour retention), and the key-value storage model. This enriches the agent's understanding of side effects and lifespan.

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 yet information-dense. It front-loads the primary purpose, then provides usage context, persistence details, and sibling tool relationships in a logical flow. Every sentence contributes new information, with 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: what it does, when to use it, how data is scoped and retained, and how it integrates with related tools. It leaves no significant contextual gaps for an agent to operate correctly.

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

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

The schema already covers both parameters with detailed descriptions and examples (100% coverage). The description's mention of 'key-value pair' adds no new semantic detail beyond what the schema provides, so it meets the baseline for high schema coverage.

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

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

The description opens with a specific verb and resource: 'Save data the agent will need to reuse later.' It clearly distinguishes itself from siblings by naming paired tools (recall, forget) and explaining the memory use case. The resource (memory) is unambiguous.

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

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

Provides explicit when-to-use guidance with concrete examples ('a resolved ticker, a target address, a user preference'). It names alternative tools (recall, forget) but does not explicitly state when NOT to use this tool. The absence of a 'when-not' clause keeps it slightly below a perfect score.

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

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

Annotations already declare this a safe, idempotent read. The description adds substantial behavior beyond annotations: internal cascading of lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguity behavior returning figi_candidates rather than asserting, explicit unresolved list, and source-labelled identifiers. 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?

Long but densely informative; the opening example queries and 'Use FIRST' directive make it front-loaded. Most sentences earn their place by covering type-specific behavior, matching pitfalls, and degradation semantics, though minor redundancy around replacing manual lookups and a somewhat sprawling structure prevent a 5.

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

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

With no output schema, the description bears the burden of explaining return values and call outcomes. It covers returned identifiers, unresolved items, figi_candidates, source labels, RxNorm citations, failure/degradation behavior, supported input formats, and per-type scope. Nothing an agent needs to select or invoke this tool correctly 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 description coverage is 100%, yielding a baseline of 3. The description adds critical semantics beyond the schema: concrete input examples (AAPL, 0000320193, CH0038863350), ISIN-to-LEI resolution behavior, the bond issuer-name matching rule, and the 'ENTITY NAME ONLY' restriction to avoid trailing security-class words.

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

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

States a precise verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers.' It distinguishes its role from sibling tools by framing itself as the entry point ('Use FIRST whenever you have a name but need an ID') and by enumerating concrete example queries and supported 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?

Explicitly provides when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and gives behavioral usage constraints (pass the issuer exactly as printed, not the full noun phrase). Lacks explicit when-not-to-use instructions or named alternative tools, so it doesn't reach 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?

Goes beyond annotations by explaining the tool 'Probes each entity ... with ai_visibility_check' and returns 'a ranked list with score, confidence, signal density per entity'. This adds behavioral context not covered by the read-only, idempotent annotations. No contradiction found.

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

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

Three sentences with no fluff. The opening line states the core purpose, followed by method and use case. Every sentence earns its place, making it 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 there is no output schema, the description fully explains the return format ('ranked list with score, confidence, signal density per entity') and gives a practical use case. Combined with schema covering inputs, it provides a complete picture for the agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds narrative about 'your brand + N competitors' and subject/competitor roles, but these are already in the schema, adding little extra meaning.

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

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

Clearly states the specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes from single-entity sibling ai_visibility_check by emphasizing side-by-side comparison and ranking, making the tool's purpose unmistakable.

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

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

Provides a clear use case: 'Useful for competitive AI-marketing audits' with a concrete example. It implies this is the multi-entity counterpart to ai_visibility_check, but 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 mark readOnly/openWorld/idempotent, and the description adds behavioral context: it fans out across two services, degrades gracefully on partial failures, and notes bundlephobia's first measurement can take 5-30s. It also discloses the sources_failed field. 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?

Five dense sentences, each earning its place: purpose, usage, return payload, ecosystem scope, and failure mode. It's front-loaded with the core implication and structured for skimming.

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 composite tool with no output schema, the description lists the summary block fields, per-advisory detail, links, alternative versions, and failure behavior. It covers edge cases (timeout, non-NPM packages) and gives a complete picture of what the agent will receive.

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 both parameters with 100% coverage, including package name format and version default behavior. The description does not add new parameter-level meaning beyond restating the schema, so the baseline of 3 applies.

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

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

The description clearly states a specific verb and resource: a composite 'should I add this npm package to my project' check. It names the data sources (deps.dev and bundlephobia) and specific checks (license, advisories, bundle size, etc.), distinguishing it from any sibling tool (none cover npm package adoption).

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 trigger phrases ('is X safe / popular / small', 'what does adding lodash cost me') and explicitly scopes to NPM in v1, directing non-NPM ecosystems to deps.dev:version directly. This provides both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds return field information (biography, prizes, motivation) but no additional behavioral traits. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that efficiently states the tool's purpose and return content. Every word earns its place with no redundancy.

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

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

For a simple read-only search tool with rich annotations and an output schema, the description is complete. It covers what the tool searches and what it returns, though it omits usage guidance relative to siblings.

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 and examples. The description only repeats the parameter usage ('by name and/or category') without adding new meaning beyond the schema.

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

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

The description clearly states the tool searches Nobel Prize laureates by name and/or category, with a specific verb and resource. It does not explicitly differentiate from sibling tools like get_prizes_by_year, but the purpose is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_prizes_by_year or entity_profile. The description only implies usage for searching laureates, with no exclusions or alternative recommendations.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds non-obvious details: BGE-base-en embeddings, 500-char overlapping windows, the 200K char truncation with a flag, and the exact return fields (character offsets, similarity scores). 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 purpose in the first sentence and remains information-dense throughout. It is slightly verbose due to technical specifics (embedding model, window size) but each sentence contributes to behavioral transparency or usage guidance; appropriately sized overall.

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

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

With no output schema, the description fully discloses the return format (passages with offsets and similarity scores), edge cases (truncation over 200K chars), and operational context (pairing with ask_pipeworx_grounded). This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for all three parameters, providing a solid baseline. The tool description adds context by clarifying that 'text' should be already-fetched content (e.g., SEC 10-K, article) and reinforcing the natural-language nature of 'query' with examples, which aids correct invocation.

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

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

The description opens with a specific verb and resource: 'Semantic search INSIDE a fetched record.' It clearly differentiates from siblings by emphasizing it operates on already-fetched text, not on external sources, and states the output (top-N passages with offsets and scores).

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 says 'Use when the record is too big to cram into the prompt' and recommends pairing with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides both when-to-use and an alternative approach.

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

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

Despite annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) providing a basic safety profile, the description adds substantial behavioral context: OAuth account required, phone verification with a 10/day cap, webhook auto-disabled after 10 consecutive failing runs, and a signing secret returned only once. No contradiction with annotations is present.

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

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

The description is information-dense and front-loaded with purpose, but it is a long single paragraph covering many details. Each clause earns its place, but the density and length prevent a perfect 5. The structure uses colons and examples effectively, making it scannable despite its 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 complex tool with nested objects, 3 parameters, and no output schema, the description is remarkably complete. It covers return value (new subscription id), all supported types with examples, delivery channels, authentication prerequisites, verification steps, rate limits, and failure behavior. An agent has sufficient information to select and invoke this tool correctly without additional 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%, with the schema already containing detailed descriptions for type, params, and delivery. The description adds meaningful usage context beyond the schema: concrete examples for each subscription type, the requirement for verified phone numbers, the always-on feed channel, and delivery constraint warnings. While not entirely novel, this supplemental meaning justifies a score 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and explicitly stating it returns the new subscription id. The supported types and delivery channels further reinforce the tool's unique purpose.

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

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

The description provides clear context for when to use the tool: to create a subscription that monitors live data, with explicit account requirements (Pipeworx OAuth, not anonymous/BYO) and a note that feed delivery is always on and can be pulled via recent_alerts. However, it does not explicitly state when not to use it or name alternative tools like list_subscriptions/unsubscribe for managing existing subscriptions, so it stops short of a full 5.

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

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

The description discloses that it returns category-bucketed example questions with the exact tool + argument shape, and explains the behavior with and without a topic. Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the additional context about return structure and live catalog adds value without contradiction.

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

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

The description is long but well structured, starting with example queries, then purpose, then return details, then parameter guidance. Every sentence carries useful information for an onboarding tool, though a few redundant examples could be trimmed.

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

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

Despite having no output schema, the description fully explains the return value (category-bucketed example questions with tool + argument shapes), usage context, parameter behavior, and even lists the target categories. It is complete for an onboarding tool with strong annotations.

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

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

The schema already fully documents the topic parameter with an exact list of options and the behavior when omitted (100% schema coverage). The description adds little beyond echoing the examples, so it does not significantly surpass the schema's baseline.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for an agent to discover what questions can be asked and returns category-bucketed example questions. It distinguishes itself from siblings like discover_tools by positioning it as the first tool to use and by mentioning specific meta-tools it helps learn to 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?

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and gives example prompts. It also explains when to pass a topic vs. omit it. However, it does not explicitly contrast with sibling tools like discover_tools, so it lacks an explicit exclusion statement.

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 significant behavioral context beyond the annotations: it explains that the subscription is deactivated rather than deleted, and that historical events remain available via recent_alerts. It also discloses the ownership enforcement rule. No contradiction with annotations; destructiveHint=false is consistent with 'not deleted'.

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: first states the core action, second provides essential constraints and consequences. No fluff, every phrase carries meaning. Purpose is front-loaded.

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

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

For a simple one-parameter tool with no output schema, the description fully covers the necessary behavior: what it does, ownership requirements, side-effect behavior (deactivation), and how it relates to other tools (recent_alerts). Annotations cover idempotency and destructiveness, so nothing 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 covers the parameter fully (id, uuid, returned by subscribe), so baseline is 3. The description adds the ownership semantics—'you can only cancel your own subscriptions'—which clarifies the meaning of the id beyond its format and origin, making the parameter more actionable.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' This clearly distinguishes it from sibling tools like subscribe (which creates subscriptions) and list_subscriptions (which lists them). The ownership constraint further clarifies its scope.

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

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

The description gives clear context: cancel by id, ownership enforced, and id must be from subscribe. It implicitly tells users when to use this tool (when they own a subscription and want to stop it), but it does not explicitly mention alternatives like list_subscriptions for viewing current subscriptions. Thus it is clear but lacks explicit exclusions or alternative naming.

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 significantly enriches the annotations by explaining failure modes: 'could_not_verify' means the check did not happen and carries verification_error, while 'unsupported' means no source exists. It also discloses the SEC EDGAR fast path for financial claims and the grounded pipeline for other claims, adding operational detail beyond the readOnly/idempotent hints.

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

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

The description is dense and covers many aspects—usage triggers, routing, verdicts, caller warnings—but it remains well-organized and front-loaded. A few phrases like 'Replaces 4–6 sequential calls' could be trimmed, but overall every section earns its place and the structure aids comprehension.

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

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

With no output schema, the description fully specifies the return shape: verdicts, actual value with citation, reasoning, and the verification_error structure. It handles edge-case semantics (could_not_verify vs unsupported) and explains routing and tolerance behavior, making it complete for a complex verification tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic context by explaining how tolerance_pct interacts with the claim wording and how it can be used for hallucination detection ('set 1–2 for hallucination detection'), which goes beyond the schema's basic description of the 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 opens with concrete trigger phrases and explicitly states the tool performs natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by focusing on verdict-based fact-checking rather than general Q&A or research, and gives a concrete example ('Apple's FY2024 revenue was $400 billion').

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 an explicit 'Use whenever' statement for fact-checking user claims and gives routing guidance for company-financial claims versus all other claims. It does not name specific sibling tools as alternatives or exclusions, but it clearly communicates when this tool is appropriate and how it falls back internally, which is strong guidance.

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