swisstransport

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

Annotations already cover read-only, open-world, and idempotent behavior. The description adds valuable context beyond these: the tool makes external LLM calls, the default model is free, and passing _apiKey invokes Anthropic with direct costs to the user. It also discloses the return shape (per-model plus combined view), giving the agent a fuller behavioral picture.

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

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

Three sentences, front-loaded with action and output. The first sentence states what it does and the output metric. The second explains model options and cost. The third gives return format and use cases. Every sentence earns its place with no filler.

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

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

Despite no output schema, the description explicitly lists the per-model return fields and mentions a combined view. It conveys the tool's scope, default behavior, cost implications, and typical use cases. For a moderate-complexity probe tool with good annotations and full schema coverage, this is complete.

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

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

Schema description coverage is 100%, so the input schema already fully documents all four parameters. The description reinforces the default model and API key behavior but adds little beyond the schema; for example, the '_apiKey only needed if anthropic is in models' nuance appears in both. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know' and clearly states the scoring output (0-100 per model). It covers general entities (business/brand/product/topic) and returns a structured result, making the tool's role distinct from query-style siblings 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 provides clear context for use by listing follow-on use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and notes the default free model versus the BYO-key Anthropic option. However, it does not explicitly name alternatives or exclusion criteria, such as 'for competitor-specific analysis use scan_competitor_ai_presence 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it routes to many tools, fills arguments, returns citations, works on every tier, and is a single fast call. These details go beyond what annotations provide, earning a good score.

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

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

The description is longer than typical but for a default entry point with complex routing behavior, it earns its length. It front-loads the key instruction (PREFER OVER WEB SEARCH) and then provides examples and alternative tool guidance. Every sentence contributes value, though some redundancy exists (e.g., listing many data types 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?

This is a complex routing tool with no output schema, so the description needs to explain what users get back. It does mention "structured answer with stable pipeworx:// citation URIs", which is a key detail. It also covers common invocation patterns and fallback tools. Missing details like error behavior or exact response format prevent a 5, but it is fairly complete for a discovery/default 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%: every parameter is described as an alias for 'question', and the question property explicitly states it accepts aliases. The description adds example questions but no additional parameter-specific semantics. With full schema coverage, baseline is 3, and the description does not deviate from that.

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

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

The description clearly states what the tool does: it answers factual questions about real-world entities by routing to 5,529 tools across 1,455 verified sources and returning structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as step-ups for different needs, making its scope unmistakable.

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

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

The description provides explicit when-to-use guidance: "PREFER OVER WEB SEARCH" for numerous question types, "START HERE for most questions — this is the default entry point", and even gives example prompts. It also states when NOT to use it: "for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research". This is textbook usage 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?

Adds significant behavioral context beyond annotations: candidate routing improvements are enabled live, no candidate is currently active, and it explicitly states it is a full working router with no fallback. This clarifies the experimental nature and assures functionality.

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 pack substantial information: identity, current status, and usage. Slightly redundant with 'identical' and 'exactly,' but each sentence earns its place, making it concise yet informative.

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 (a universal router) and no output schema, the description provides enough context: it explains the beta nature, current state, usage, and that it's fully functional. It relies on prior knowledge of ask_pipeworx but is sufficiently complete for an agent familiar with the sibling.

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

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

The input schema already has 100% coverage with rich alias descriptions. The description merely says 'same arguments' as ask_pipeworx, adding no new parameter-level semantics beyond referencing the sibling tool, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx and the grounded variant by emphasizing its experimental routing improvements.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also references the alternative (ask_pipeworx) and clarifies that results are compared against the stable router, giving clear context for 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?

While annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, the description adds substantial context beyond those: the structured return shape with evidence and refusal reasons, the explicit refusal modes, and the extra LLM call cost. There is no contradiction 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?

The description is dense but every clause earns its place: purpose, routing behavior, extraction guarantee, return payload, refusal reasons, when to use, and when to avoid. It is front-loaded with the core purpose and does not waste words.

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

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

Since there is no output schema, the description fully compensates by describing the exact return contract, including the success shape and every refusal reason. It also provides cost guidance and alternative selection, making the tool's behavior completely understandable in context.

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

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

Schema coverage is 100%, with all five aliases documented in the input schema itself. The description only refers to 'question in natural language' implicitly via 'fills arguments' and does not add additional parameter-level semantics, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb and resource. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it extracts answers using ONLY the tool result contents, providing a clear functional identity.

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

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

Explicit guidance is given: use when answers will be quoted, cited, or acted on, and prefer ask_pipeworx for casual lookups. It also names the alternative tool directly and mentions the extra LLM call cost, making the trade-off obvious.

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 read-only/idempotent annotations, disclosing resolver match confidence, low-confidence short-circuiting, closed-market blocking, wide-spread liquidity flags, cancellation-rule parsing, and news fallback behavior. This gives the agent a detailed mental model of what will happen.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and a clear opening sentence. While verbose, the complexity of the tool justifies the detail; it could be trimmed slightly but remains effective.

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?

Provides exhaustive coverage of the tool's behavior: input variants, classifier taxonomy, fan-out examples, response shapes, resolver contract, parent-event extraction, news fallback, safety mechanisms, and resolution-rule risk. Despite no output schema, the description fully equips an agent to use the tool safely and effectively.

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

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

The input schema already covers all three parameters with descriptions (market format, depth enum, include_raw behavior). The description does not add parameter-specific meaning beyond that, so the baseline 3 is appropriate given the 100% schema coverage.

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

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

The description states a specific action: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling research tools by focusing on market-vs-model comparison and bet evaluation, and includes concrete use-case phrases like 'should I bet on X'.

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 when to use the tool ('Use for "should I bet on X"...') and provides examples of the fan-out behavior. It does not explicitly say when NOT to use it or name alternative tools, so while the context is clear, exclusions are missing.

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?

Even though annotations already declare read-only, idempotent, and non-destructive behavior, the description adds substantial context: it details specific data sources (SEC EDGAR/XBRL, FAERS), mentions handling of off-calendar fiscal years (AAPL, NVDA), describes result sorting, and notes citation URIs. This goes well beyond the structured annotations and fully discloses behavioral traits.

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 user-intent triggers and a clear core statement, followed by compact details about data sources, sorting, and returns. It is slightly repetitive in emphasizing the preference over sequential lookups twice, but every sentence carries useful information and the structure is logical.

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

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

Given no output schema, the description sufficiently communicates what the tool returns ('paired data + pipeworx:// citation URIs per entity') and how results are sorted. It covers the main behavioral nuances and data sourcing, though it could mention potential limits like missing data or response format edge cases; overall it is complete for practical 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, but the description enriches parameter meaning by explaining what each 'type' pulls (e.g., 10-K revenue/net income/cash/long-term debt for companies; FAERS counts for drugs) and gives explicit value examples. It adds value beyond the schema without fully documenting every potential edge case or format restriction.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call, with specific trigger phrases like 'X vs Y' and 'which is bigger'. It distinguishes from sequential single-entity lookups by explicitly preferring this tool for comparisons, and it conveys the concrete resource (SEC EDGAR/XBRL and FAERS data) used.

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

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

The description provides explicit when-to-use guidance with example queries and states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also differentiates behavior by type (company vs. drug) and clarifies output sorting, giving the agent clear conditions for selecting this tool over alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context beyond these: account requirements, paid tier for 'thorough', parallel tool routing, explicit gaps[], never-invented evidence, resolvable citation URIs, semantic excerpting, contradiction scanning, and latency expectations. No contradiction with annotations exists.

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

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

The description is long but information-dense; every sentence earns its place by covering auth, alternatives, output format, limitations, and performance. It is a single dense paragraph that could benefit from bullet points for scannability, but it avoids redundancy and remains appropriately sized for the tool's complexity.

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

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

For a tool with two parameters and no output schema, the description fully covers the prerequisites, alternatives, output packet (evidence, confidence, source, fetched_at, citation), failure behavior (gaps[]), contradictions, and expected latency. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

Although schema coverage is 100%, the description enriches the `depth` parameter by explaining what each level does in practice: quick=single hop, standard=gap recovery+contradictions, thorough=iterative lead-chasing+contradictions. It also clarifies that `question` can be broad and multi-part, which is not evident from the schema alone.

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

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

The description clearly identifies deep_research as grounded multi-source research across Pipeworx's structured data sources in one call, explicitly distinguishing it from open-web search. It uses a specific verb+resource formulation and differentiates from siblings like ask_pipeworx by noting it is for broad/multi-part structured-data questions.

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 and when-not-to-use guidance: use ask_pipeworx if not signed in, for single lookups, or for breaking/current news; use deep_research for broad/multi-part questions over structured data. It also explains when to choose each depth level, including gap recovery and iterative follow-up behavior.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it returns the top-N most relevant tools with names, descriptions, and full input schemas, and emphasizes that results are ready to call directly with no second schema lookup. It does not discuss rate limits or error behavior, but adds sufficient value.

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

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

The description is front-loaded with the core function and then provides usage guidance, return behavior, and domain coverage. The domain list is somewhat long but serves as concrete scope, and every sentence contributes purpose, context, or result details. It remains focused and readable.

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

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

Given the tool's moderate complexity, a single required parameter, rich schema with examples, and no output schema, the description covers what the tool does, when to use it, and what it returns. It could be more explicit about result structure (e.g., relevance scores, exact fields), but it conveys the essential contract: discovery of callable tools with full schemas.

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 has 100% description coverage, documenting query, q, task, limit, search, and description with aliases and examples. The description doesn't add new parameter-level semantics; it reinforces that the query is a natural language task description and that results are top-N (related to limit), but the schema already carries the 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?

Description opens with a specific verb and resource: 'Find tools by describing the data or task.' It then enumerates concrete domains (SEC filings, FDA drugs, etc.) and explicitly frames the tool as the way to browse/discover available options, distinguishing it from sibling tools that perform specific tasks. The 'Call this FIRST' instruction further clarifies its unique role as a meta-tool.

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

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

It clearly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It also hints at a when-not ('not just one answer'), suggesting it's not for retrieving a single direct answer, though it doesn't explicitly name alternative tools or provide formal 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 (readOnlyHint, idempotentHint, destructiveHint=false) are complemented by the description's behavioral details: parallel fan-out across five sources, soft-fail for the sunsetting USPTO API, GDELT→GNews fallback, and specific output fields. 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 lengthy and includes example queries, a priority directive, output breakdown, and caveats. It is front-loaded and well-organized, though slightly verbose; every sentence adds value (e.g., patent sunset soft-fail).

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 covers return values, data sources, fallback behavior, and input constraints. It provides a complete picture for the agent to invoke the tool correctly and set expectations for results.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the parameter guidance (ticker or zero-padded CIK, names not supported) without adding new semantics beyond the schema. It does not clarify format beyond what's 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 clearly states the tool's function: "full cross-source profile of a US public company in ONE parallel call." It distinguishes itself from sibling tools like resolve_entity and compare_entities by specifying the holistic multi-source scope and explicitly noting that names are not supported.

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 usage guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also directs users to resolve_entity when only a name is available, clearly defining when not to use this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which cover the destructive and idempotent nature. The description adds some context about clearing sensitive data but does not significantly extend behavioral disclosure beyond annotations. No contradiction exists.

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

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

Three short sentences: purpose first, then usage scenarios, then related tools. Every sentence earns its place with no redundancy or filler.

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

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

For a simple one-parameter destructive tool with clear annotations and no output schema, the description fully covers purpose, usage, and relationship to sibling tools. Nothing essential is missing.

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

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

Schema coverage is 100% and the single parameter 'key' is described as 'Memory key to delete'. The description repeats 'by key' but adds no new semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action: 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by focusing on deletion, and later pairs with 'remember and recall' to position itself in the memory lifecycle.

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 when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also mentions complementary tools ('Pair with remember and recall'), making the usage context clear and actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context by explaining the fetch-and-extract process and stating the output is a 'single text blob ready to drop at site-root/llms.txt,' which goes beyond the schema and annotations.

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

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

The description is compact and front-loaded, with the main action in the first clause. The 'Useful for' list adds value without unnecessary detail, and no sentence is wasted.

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

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

For a simple two-parameter read-only tool with strong annotations, the description covers the core behavior, output format, and intended use cases. It adequately addresses the lack of an output schema by specifying the format of the returned blob.

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 has 100% coverage with descriptions for both 'url' and 'max_links,' so the description doesn't need to add parameter semantics. It merely references the extraction process, which doesn't add new meaning to 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 a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly explains the process (fetches page, extracts title/description/links) and output, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context for when to invoke. It does not explicitly list alternatives or exclusions, but the use cases differentiate it from sibling tools.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds that it returns 'up to the requested number of next departures,' which indicates the tool returns upcoming departures and respects a limit. However, it does not disclose other behavioral traits like sorting, time zone handling, or error behavior, so it adds only modest value beyond annotations.

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

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

The description is two short, front-loaded sentences that state the core purpose and the return behavior with no filler. Every word earns its place, making it highly concise and well-structured.

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

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

Given the tool's simplicity (3 parameters, all documented, with an output schema present), the description is largely sufficient. It explains the core function and the limit behavior, while annotations cover safety. It does not need to detail return values because an output schema exists. A minor gap is the lack of mention of any required time/date parameters (which the schema also omits), but for a basic connection query, the description is complete enough.

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

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

Schema description coverage is 100%, meaning all parameters (from, to, limit) have descriptions. The description rephrases 'two Swiss locations' for from/to and mentions 'number of next departures' for limit but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool's function: getting public transport connections between two Swiss locations, which distinguishes it from siblings like get_stationboard (departures for a single station) and search_stations (station lookup). It uses a specific verb 'Get' and resource 'connections'.

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 usage for point-to-point connection queries but does not explicitly mention when not to use this tool or name alternatives. Sibling tools exist (e.g., get_stationboard, search_stations), but no guidance is given on choosing between them, so the context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the 'live' attribute, implying real-time data that may change between calls, but provides no further behavioral context such as rate limits or data freshness guarantees.

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?

A single, focused sentence that is front-loaded with the key verb and resource. No unnecessary words or repetition.

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

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

The tool is simple with only one required parameter, full schema coverage, and an output schema. The description sufficiently covers the core purpose and context, leaving no critical gaps given the supporting metadata.

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

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

Schema description coverage is 100%, with both 'station' and 'limit' fully documented in the input schema. The description itself does not add parameter-level detail, so the baseline score 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 the verb ('Get'), resource ('live departure board'), and scope ('Swiss public transport station'). It distinguishes itself from siblings like 'get_connections' and 'search_stations' by focusing specifically on station departures.

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. There is no mention of exclusions, prerequisites, or comparison with sibling tools like 'get_connections' or 'search_stations'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying that subscriptions are scoped to the caller and that active subscriptions are returned by default, with an option to include cancelled ones. It also lists the exact return fields, which goes beyond the annotation layer.

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 wasted words. The first sentence front-loads the action and output, and the second sentence adds practical usage context. It is appropriately sized for the tool's simplicity.

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

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

For a simple read-only list tool with a single optional parameter and no output schema, the description is complete: it states scope (caller's subscriptions), default behavior (active only), the include_inactive option, the exact return fields, and when to use it. The annotations cover safety traits, so no key information is missing.

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

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

There is only one parameter, include_inactive, and its schema description fully covers its semantics ('Include cancelled subscriptions in the response (default false)'). The main description adds no further parameter-level detail. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool 'List the caller's active subscriptions', identifying a specific verb and resource. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reviewing existing subscriptions, and it enumerates the return fields, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke this tool relative to actions like subscribing or cancelling, effectively naming the alternatives (subscribe/unsubscribe) without needing to reference them directly.

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 generic annotations, the description discloses significant behavioral traits: the claim_token mechanism for later retrieval, a daily rate limit of 5 per identifier, that it is free and doesn't count against quota, and how the team processes feedback ('reads digests daily and signal directly affects roadmap'). These are valuable operational details that go well beyond the annotations.

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

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

Though the description is lengthy, every sentence earns its place and there is no fluff. It is front-loaded with the core purpose, then methodically covers use cases, exclusions, mechanisms, and operational notes, making it both comprehensive 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?

Despite lacking an output schema, the description adequately explains what filing returns (a claim_token) and how to later check status. It also covers rate limits, excluded scopes, and response handling, ensuring the agent has sufficient context to invoke this tool correctly without needing 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%, so the baseline is 3. The description adds value by explaining the claim_token usage ('pass the pwfb_… token that filing returned, with no other arguments') and by advising not to paste the end-user's prompt, which clarifies message content. This nuanced guidance warrants an above-baseline score.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the verb (tell), resource (Pipeworx team), and purpose. It also distinguishes this from sibling tools by explicitly limiting it to Pipeworx tools and contrasting with other MCP servers, so it is clear how to separate it from similar feedback avenues.

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

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

The description provides explicit when-to-use conditions: '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 gives a clear exclusion for other MCP servers and a 'Not sure?' heuristic to disambiguate, which is excellent guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds meaningful context: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This discloses data provenance, privacy, and freshness 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 front-loaded with a clear purpose, followed by a compact bulleted usage list and essential data-governance/caching caveats. Every sentence adds distinct information; no fluff or repetition.

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

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

Despite no output schema, the description states the return contents ('top tools, top packs, and total call volume', 'just (pack, tool, count)'), and covers privacy, aggregation, and caching. For a single-optional-param read-only tool, this is fully 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 a detailed enum description, so baseline is 3. The description adds value with 'Cached 5min-1h depending on window,' which is a parameter-dependent behavior not present in the schema, though it doesn't map specific windows to cache durations.

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.' This is a specific verb+resource+scope that clearly differentiates it from siblings like ask_pipeworx or discover_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?

Provides explicit 'Useful for' list with three concrete scenarios (discovering hot data sources, confirming canonical tools, checking alignment with agent needs). It does not explicitly name alternatives or when-not-to-use, so it misses the 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?

Annotations already declare read-only and idempotent, and the description adds rich behavioral detail: the Jaccard similarity threshold, placeholder filter, partition-sum threshold (>3pp), fill check against live CLOB depth, and the realizable_edge_pp condition. It also describes the response shape and failure modes (null arb signal for >20% placeholder).

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the core purpose and usage. Every section adds unique value, though the density makes it slightly heavy; a more concise summary could merge some sections.

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, this is exceptionally complete: it covers modes, thresholds, filters, output shape, fill-check behavior, and cross-references to sibling tools. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema covers 100% of parameters with descriptions, and the tool description goes further: it provides example slugs/URLs for `event`, explains the search behavior for `topic`, and embeds the 'recommended' guidance for event mode. The 'Full Polymarket URLs also accepted' detail is extra schema value.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes this tool from siblings like polymarket_edges, polymarket_fill_risk, and polymarket_kalshi_spread by focusing on arbitrage via these specific checks.

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

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

It explicitly explains when to use each mode: no args for trending_scan, `event` for a specific market, `topic` for cross-event scanning. It also directs users to `polymarket_fill_risk` for custom sizing, providing an alternative. The fill check section includes a clear 'do not trade it' condition.

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/idempotentHint annotations by disclosing internal caching ('Cached 1h at the KV level keyed on all knobs'), response diagnostics, and detailed model assumptions (e.g., per-sport alpha coefficients, placeholder-slug filters, Fed signal unreliability). It also explains the warning mechanism for 24h moves, providing deep 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 and dense, but it front-loads the core purpose and uses clear visual segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) that aids scanning. While some sentences are highly technical, each contributes valuable details for a complex tool, so it is not unnecessarily verbose.

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?

In the absence of an output schema, the description thoroughly documents the response structure (by_segment, fed_candidates/fed_note, _diagnostics) and provides field-level explanations (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume, and the 24h-move warning). It also covers edge cases like placeholder slug filtering and Fed signal unreliability, making it exceptionally complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful interaction context beyond individual parameter descriptions, such as explaining why min_partition_leg_kelly exists ('Partition arbs always return kelly_fraction_half=0 at the parent level by design') and how min_liquidity/max_spread_pp act as 'tradeable-edge filters.' This justifies a score above baseline.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It then differentiates the tool from pagination-heavy alternatives through the phrase 'without paging hundreds of markets' and names three distinct model families, making the scope and output 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?

It provides a clear context: 'Built for "what should I bet on today"' and explains the purpose of the 'TRADEABLE-EDGE KNOBS' for filtering. However, it does not explicitly mention when NOT to use this tool or name alternative sibling tools like polymarket_arbitrage or polymarket_fill_risk, so it lacks explicit exclusion guidance.

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

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

Annotations already establish read-only and idempotent behavior; the description adds crucial details about snapshot timing (cache-miss triggers, gaps mean no scan), history bounded by 60-day TTL, and decay computed from daily closes of edge_pp_net not intraday. This greatly exceeds the annotation baseline.

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

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

The description is well-structured with ARGS, RESPONSE, and LIMITS sections. It front-loads the purpose, and every sentence contributes necessary information, especially given the lack of an output schema.

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 thoroughly covers purpose, arguments, response shapes (tracked, expired, snapshot_dates), and important caveats (TTL, gaps, non-intraday decay). It compensates fully for the absent output schema and leaves little room for ambiguity.

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

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

The schema covers 100% of parameters with descriptions for days and window. The description restates defaults and max but does not add additional meaning beyond the schema. Per the high-coverage rule, 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 'Edge persistence and decay telemetry' and explicitly frames the user question it answers ('how long has this edge existed and is it shrinking?'). This clearly defines the tool's function and distinguishes it from siblings like polymarket_edges (which scans edges) by focusing on time-series and lifespan.

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

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

The description gives clear usage context: deciding if an edge is new vs old/decaying, with the analogy of a 3-week-old wide edge being a different trade. It implies when to use the tool for persistence/decay analysis, and LIMITS notes that it is not intraday data. However, it does not explicitly name alternative tools 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 mark readOnlyHint=true and idempotentHint=true, but the description adds far richer behavioral detail: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd), explains per-leg fills, thin_legs, and forced_directional_risk, and warns about partial-fill consequences. No contradiction with annotations.

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

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

The description is long and dense, but every sentence carries actionable information. It front-loads the core purpose and uses clear mode markers (SINGLE-MARKET, BASKET). It could be improved with bullet points or line breaks, but it does not waste words.

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

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

Given the tool's complexity, no output schema, and only 4 parameters, the description fully compensates by enumerating return fields for both modes, explaining the risk of partial fills, and naming the exact outputs (verdict, capture_ratio, profit_usd, etc.). It is self-contained for an agent to decide when and how to invoke it.

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

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

Although schema coverage is 100%, the description adds significant semantic depth: clarifies that size_usd means spend for buys, target proceeds for sells, and settlement notional in basket mode; explains the auto default for side based on partition sum; and notes the 10–1,000,000 clamp. This goes well beyond the schema's basic parameter descriptions.

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

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

The description opens with a specific verb-resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly distinguishing the tool from siblings. It explicitly differentiates by naming polymarket_arbitrage and polymarket_edges as related tools and stating this is the pre-trade validation step.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains the reasoning (theoretical overround not capturable on thin books, partial fills create unhedged directional risk), effectively naming alternatives and conditions.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing safety fields, compatibility warning conditions, temporal alignment semantics, and skipped cross-type/subtype counters. It even explains edge cases like matched_pairs=0 with different skip reasons, giving the agent a thorough understanding of what the tool will report and why.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It is longer than strictly necessary, repeating some warnings (e.g., the compatibility caveat is stated in two places), but every section adds substantive information and the structure aids readability.

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 fully accounts for the response format, including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also covers edge cases like non-equivalent bet shapes and temporal mismatches, making the tool's behavior comprehensible for a complex data-fetching 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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds meaningful semantics by explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and by clarifying the relationship between the topic parameter and the explicit parameters. It also contextualizes the response fields, which helps the agent understand what the parameters will yield.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the resource and primary function. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison and explicitly describes two modes and the output structure, making the tool's purpose unambiguous.

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

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

The description provides clear guidance on when to use the tool: it explains the two input modes (pre-mapped topics vs explicit tickers) and how they override each other. It also warns that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which tells the agent when results may be invalid. However, it does not explicitly contrast against sibling tools like polymarket_arbitrage, so it misses the highest bar for alternative discrimination.

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 scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID) and that omitting key lists all keys. This is useful context beyond the schema.

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

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

Three crisp sentences front-load the main action and immediately cover the special case (omitting key). No redundant phrasing.

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

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

For a read-only, single-parameter tool, the description covers purpose, scoping, usage, and related tools. Without an output schema, no return format is required, and the implied return value is clear.

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

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

The sole parameter `key` is described in the schema as 'Memory key to retrieve (omit to list all keys)' with 100% coverage. The description repeats this without adding new detail, so the baseline 3 applies.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys,' which clearly states the action and scope. It distinguishes from siblings by naming save/delete counterparts, making the tool's 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?

It explicitly says 'Use to look up context the agent stored earlier' and pairs itself with remember and forget, making the when-to-use clear versus alternatives.

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

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

Beyond the provided annotations (readOnly, idempotent, non-destructive), the description discloses useful behavioral details: returned events carry source, citation_uri, and raw payload; mark_read:true flips read state so subsequent calls return only newer events. This adds meaningful context about side effects and return content.

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

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

The description is three sentences long, front-loaded with the main purpose, and each sentence delivers distinct value: what it does, what it returns, and how to filter/consume. No fluff.

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

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

Given the tool has five optional parameters, no output schema, and good annotations, the description fills all critical gaps: return payload format, filter mechanics, read-tracking behavior, polling suitability, and an alternative REST endpoint. An agent would know exactly how and when 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?

All five parameters are already described in the schema, so the baseline is 3. The description enhances understanding by explicitly showing a filter example ('sec_8k') and explaining the mark_read side effect, adding value beyond the schema.

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

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

The description opens with 'Pull fired events from your subscription feed,' which names a specific verb and resource. It further explains these are alerts the evaluator wrote to a persisted feed, clearly distinguishing this from sibling tools like recent_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?

The description provides clear context: it is for polling subscription alerts, includes filter options, and notes that polling works fine. However, it does not explicitly name alternatives or state when not to use this tool, 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?

Beyond the readOnly/idempotent annotations, it discloses important runtime behavior: GDELT is preferred over GNews with fallback on rate-limit or 5xx, USPTO soft-fails due to API sunset, and the return shape (changes[] grouped by source, total_changes, pipeworx:// citation URIs). This is far richer than the annotation defaults and helps set expectations for external API failures.

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

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

The description is dense but every sentence serves a purpose: triggers, data sources, fallback behavior, parameter syntax, return structure, and alternative tool. It front-loads the most actionable information and keeps structural overhead low despite the multi-source complexity.

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

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

Given the multi-source fan-out and no output schema, the description is remarkably complete: it explains the aggregation (structured changes[] grouped by source + total_changes), citation URIs, fallback logic, and failure modes. The complexity is high, but the description equips the agent with enough context to invoke correctly and interpret results.

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

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

Although schema coverage is 100%, the description adds meaningful semantics: 'since' accepts ISO or relative shorthand with typical monitoring recommendation, 'value' gives ticker vs. zero-padded CIK examples, and 'type' is constrained to company. This goes beyond the schema's field descriptions by clarifying formats and usage patterns.

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 query patterns ('What's new with X' / 'latest on Y') and then names a specific verb-resource pair: 'change feed for a company in the last N days'. It clearly differentiates itself by listing the data sources (SEC, GDELT/GNews, USPTO) and explicitly contrasts with entity_profile.

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

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

It provides explicit when-to-use guidance via natural-language triggers, explains the parallel fan-out behavior, and states a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' This gives the agent strong decision criteria beyond the schema.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds valuable context about auth-dependent persistence (authenticated users vs. 24-hour anonymous retention) and scoping by identifier. It does not mention overwrite behavior, but given the annotation coverage, this is a minor gap.

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

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

The description is three sentences, each earning its place: the first states the core action, the second gives usage context with examples, and the third explains persistence and related tools. No redundancy or filler.

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

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

For a simple two-parameter store with no output schema, the description covers purpose, usage, persistence model, and related tools. The only minor omission is overwrite semantics, but the annotations and simple interface make the tool's behavior sufficiently clear.

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

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

The schema covers both key and value with 100% coverage and includes examples. The description reinforces the key-value pair concept but adds no new parameter-level details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb ('Save data') and resource ('data the agent will need to reuse later'). It distinguishes itself from siblings by mentioning cross-session persistence and explicitly pairing with recall and forget, making the tool's role unique among the sibling tools.

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

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

Explicit guidance is provided on when to use: 'Use when you discover something worth carrying forward...' with concrete examples (ticker, address, preference). It also directs users to recall and forget for retrieval and deletion, giving clear alternatives.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: identifiers from multiple sources are labelled, unresolved identifiers are listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through internal endpoints. These details go well beyond the annotation flags.

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

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

The description is long but dense, opening with real user queries to anchor intent. Each sentence adds value (source labelling, graceful degradation, replacement of manual lookups), though the company sub-description is somewhat run-on and could be more tightly 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?

With no output schema, the description carries full responsibility for explaining return values. It lists every identifier type per entity type, explicitly addresses unresolved identifiers, and notes fallback behavior, making it sufficiently complete for a complex multi-source lookup tool.

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

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

Input schema covers both parameters with descriptions (100% coverage), so baseline is 3. The description adds semantic context by specifying what each type returns (e.g., company yields CIK/ticker/LEI/FIGI; drug yields RxCUI/ingredient/brand) and reinforces accepted value formats, enhancing the baseline schema info.

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 resolves user-spoken names to canonical identifiers, with specific resource examples ('ticker', 'CIK', 'LEI', 'RxCUI') and explicit positioning as the first stop when a name needs an ID. This distinguishes it from sibling tools like entity_profile or compare_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 provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and enumerates supported types and input forms. It does not name alternative tools for when an ID is already known, but the 'FIRST' framing implies precedence, so it stops short of full when-not/alternatives coverage.

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

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

The description discloses key behavioral details beyond the annotations: it internally probes each entity with `ai_visibility_check`, treats the first entity as the 'subject' for narrative, and returns a ranked list with score, confidence, and signal density. This adds value beyond the read-only/idempotent hints, though some details like error handling or rate limits are omitted.

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

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

The description is three sentences, each earning its place: core purpose, mechanism/behavior, and use case with output format. It is front-loaded and free of redundant details, making it easy to parse quickly.

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

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

The tool has no output schema, so the description compensates by explicitly stating the return format (ranked list with score, confidence, signal density). It also provides a concrete usage scenario and notes the entity count constraint. Minor gaps remain (e.g., rate limits, error cases), but for a read-only tool with well-documented parameters, it is nearly complete.

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

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

Schema coverage is 100%, and the schema already describes all parameters, including the first-entity-as-subject behavior for `entities`. The description does not add new parameter-specific meaning beyond what the schema provides, so it remains at the baseline for high schema coverage.

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

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

The description clearly states the tool's function: comparing AI visibility across multiple entities side-by-side. It distinguishes itself from the sibling tool `ai_visibility_check` by explicitly referencing it and emphasizing the multi-entity comparison and ranking. The verb 'compare' and resource 'AI visibility across multiple entities' are specific and unambiguous.

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

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

The description provides a clear context for use ('competitive AI-marketing audits') and an illustrative example question. It implicitly indicates this tool is for multi-entity comparison, but it does not explicitly state when not to use it or name alternatives like `compare_entities`. Thus it has clear context but lacks explicit exclusions.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: it is a composite call fanning out across two services, it may take 5-30s on first bundlephobia measurement, and partial failures degrade gracefully with a 'sources_failed' field. This explains latency, failure handling, and aggregation behavior, which directly affects how an agent interprets results.

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

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

The description is information-dense yet well-structured: it opens with purpose, then usage triggers, return summary, ecosystem scope, and failure behavior. No sentence is redundant; every phrase adds value essential for invoking a composite tool without an output schema. Front-loading the main purpose makes it immediately scannable.

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

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

Given the tool's complexity (multi-source composite, no output schema) and rich annotations, the description fully compensates. It enumerates the summary block fields (is_latest, license, advisory_count, etc.), mentions per-advisory detail, links, alternative versions, and the graceful degradation mechanism. This is a complete picture for an agent to understand what the tool returns and how to handle partial results.

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

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

The input schema already has 100% coverage, thoroughly describing both 'package' (npm package name, scoped packages accepted) and 'version' (specific version, default latest). The description does not add new parameter-level detail beyond what the schema provides; it reinforces the purpose but doesn't expand on syntax or edge cases. 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 crystal-clear statement: 'Composite should I add this npm package to my project' check in ONE call.' This identifies the specific verb, resource, and scope, and distinguishes it from siblings by narrowing to npm only. It explicitly details the two data sources (deps.dev and bundlephobia) and the types of information gathered, leaving no ambiguity about the tool's 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 gives explicit usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This tells agents exactly when to reach for this tool and when to go elsewhere.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds the scope of Swiss public transport and station types, but does not disclose any additional behavioral nuances such as fuzzy matching, pagination, or result ordering. With annotations covering safety, the description provides modest added 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 a single, front-loaded sentence with no unnecessary words. It efficiently conveys the action, resource, and scope.

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 (one parameter, strong annotations, and an output schema), the description is complete. It provides enough information for an agent to invoke the tool correctly without additional explanation.

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 has 100% coverage for the single 'query' parameter, including examples. The description adds no further parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Search', the resource 'Swiss public transport stations', and specifies the types (train, bus, tram). This distinguishes it from sibling tools like get_connections and get_stationboard, which operate on station data rather than discover stations by name.

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

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

The description implies the tool is for finding stations by name, but it does not explicitly mention when to use it versus alternatives or any exclusions. The sibling tools for connections and stationboards suggest it's a prerequisite, but that connection is not made explicit in the description.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses technical behavior: the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagged, and that results include character offsets for verification. This is substantial context that annotations alone don't provide and helps the agent anticipate edge cases like long inputs.

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 five sentences but each serves a purpose: definition, use case, benefit, complementary tool, and technical limit. It is front-loaded with the core function and structured logically. No redundant phrases; all details are relevant.

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

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

Despite no output schema, the description specifies the return format (top-N passages with character offsets and similarity scores) and explains truncation behavior for oversized inputs. Combined with the annotations and schema, the agent has enough information to invoke the tool correctly and interpret results. The tool's complexity is moderate, and the description covers all necessary aspects.

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 describes all three parameters with 100% coverage, including limits and defaults. The description adds context that the text parameter is a 'fetched record' and that query is natural-language, but these are minor reinforcements of existing schema descriptions. The baseline of 3 applies because the schema carries the burden, and the description doesn't add meaningfully new parameter-level semantics.

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

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

The description opens with 'Semantic search INSIDE a fetched record', which clearly identifies the operation as a search over provided text rather than an external source. It distinguishes itself from siblings like ask_pipeworx by emphasizing 'inside a fetched record' and gives concrete examples (SEC 10-K body, article). The verb 'search' and resource 'fetched record' are specific and unambiguous.

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

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

The description explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt'. It also names a complementary tool, ask_pipeworx_grounded, and explains the pairing pattern. This goes beyond a generic statement and provides actionable guidance for tool selection.

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

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

The description goes far beyond the annotations by disclosing key behaviors: persistence requirements (OAuth only), delivery channel specifics, phone verification requirement, 10/day SMS cap, webhook signing secret returned only once, HMAC signature format, and auto-disable after 10 failed webhook deliveries. This adds substantial context about side effects and constraints not captured by readOnlyHint/destructiveHint/idempotentHint.

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

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

The description is dense and information-packed, with each sentence serving a purpose: function, auth requirement, type examples, and delivery channels. It is a bit long but well-structured with colons and parentheses to group related details. No filler words or redundancy.

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

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

Given the tool's complexity (3 params, nested delivery object, multiple subscription types, and no output schema), the description covers return values, authentication, type-specific parameters, delivery channel options, verification steps, rate limits, and webhook security. It leaves little ambiguity about how to invoke or interpret results, making it highly 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%, but the description enriches the parameter understanding with practical examples for each subscription type (e.g., 'items:["5.02"]' for officer changes, 'params:{topic:"fed"}' for polymarket edge, 'params:{series_id:"UNRATE"}' for FRED). It also clarifies the delivery.webhook behavior (HMAC verification, one-time secret) beyond the schema's terse description.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream' and that it 'Returns the new subscription id.' This is a specific verb (create) + resource (subscription) and distinguishes the tool from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 notes the prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions),' and mentions alternative pull mechanisms ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). While it doesn't explicitly say 'use recent_alerts instead of subscribing,' the context makes the relationship between subscribe and read operations clear.

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

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

Annotations already indicate a safe, read-only, idempotent operation. The description adds valuable behavioral context beyond the annotations: it explains the return format (category-bucketed examples with tool+argument shape), the source ('live catalog of thousands of tools'), and the effect of omitting vs. passing the topic parameter. No contradictions.

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

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

The description is front-loaded with the exact user queries it answers, which is useful for pattern matching. It is longer than strictly necessary but every sentence earns its place: the intro examples, the return format, and the usage directive. It is well structured and not redundant.

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

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

With no output schema, the description fully explains the return value (category-bucketed example questions with tool+argument shape). It also covers the parameter behavior, the source catalogs, and the recommended invocation context. This is complete for a simple discovery tool with one optional parameter.

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

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

Schema coverage is 100% and the schema already describes the topic parameter and its allowed values. The description adds example topics ('finance', 'pharma', 'betting') and explains the omission behavior ('full spread'), but this is marginal value over the schema's own description. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: it is 'the onboarding entry point' that 'Returns category-bucketed example questions' with the exact tool and argument shape. It clearly distinguishes itself from sibling tools like discover_tools by focusing on 'what can I ask' and explicitly names the meta-tools it teaches.

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

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

The description gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two usage modes (no arguments vs. topic). However, it does not explicitly contrast with alternatives like discover_tools or say when NOT to use it, so it misses the full 'when-not' dimension.

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 detail beyond annotations: the row is deactivated (not deleted) and historical events remain via recent_alerts. It also clarifies the ownership enforcement, which is not in the annotations. This aligns with the destructiveHint=false annotation.

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 tight, front-loaded sentences. The first states exactly what it does and the second adds the essential behavioral nuance. Zero wasted words.

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

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

For a simple single-parameter mutation tool, this description is complete: it covers the action, the ownership constraint, the soft-delete behavior, and the impact on recent_alerts. Annotations cover safety, and no output schema is needed for such a straightforward operation.

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

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

Schema coverage is 100% and the id parameter's description ('Subscription id (uuid) returned by subscribe.') already provides the meaning. The tool description only repeats 'by id' without adding further semantic value, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Cancel a subscription by id'), clearly distinguishing it from siblings like subscribe and list_subscriptions. The deactivation vs. deletion detail 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?

It provides clear context: ownership is enforced, so you can only cancel your own subscriptions, which guides when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, though that context is implied.

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 critical behavioral details: the dual-pipeline architecture, the precise meaning of each verdict (especially distinguishing could_not_verify as a non-result), the requirement not to treat could_not_verify as evidence, and the unsupported meaning. This is exactly the kind of context that helps an agent handle edge cases correctly.

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

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

The description is longer than average but every sentence earns its place: trigger phrases, pipeline details, verdict semantics, and failure-mode warnings. It could be more front-loaded (the purpose statement appears after the examples), but it remains efficient and well-structured for a tool with this complexity.

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

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

With no output schema, the description thoroughly covers the return values: verdict list, actual value with citation, and reasoning. It also addresses edge cases (could_not_verify vs unsupported) and explains the tool's efficiency (replacing 4–6 calls). For a claim-verification tool, this is complete and actionable.

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

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

Schema coverage is 100%, and both parameters already have rich descriptions (claim with examples, tolerance_pct with range and default). The description itself adds little beyond what the schema provides; it mentions 'exact percent-delta math' but the schema already explains the tolerance behavior. 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 performs natural-language claim verification against authoritative sources, with trigger phrases like 'fact check' and 'verify the claim that...'. It distinguishes itself from sibling Q&A tools by focusing on verdicts and providing two distinct verification pipelines (SEC EDGAR for financial claims, grounded pipeline for others).

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use. However, it does not explicitly mention when not to use it or name alternative tools (e.g., ask_pipeworx_grounded for general queries), so it stops short of full when-not/alternatives guidance.

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