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 indicate read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: this tool routes to 5,798 tools across 1,517 verified sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This clarifies the orchestration behavior and output nature without contradicting the annotations.

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

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

The description is longer than average but almost every part earns its place: target domains, trigger phrases, examples, and an explicit alternative. Critical guidance is front-loaded with "PREFER OVER WEB SEARCH" and "START HERE for most questions." It could be tightened slightly, but it is structurally 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?

Given the tool's complexity, the description is remarkably complete: it explains what it does, when to use it, when not to use it, provides representative examples, and describes the output as a structured answer with citation URIs. Even without an output schema, an agent has enough context to invoke this tool correctly and interpret the result.

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: all six parameters are documented as aliases for a single natural-language question, with examples. The description adds little beyond that, so it is correct to give the schema the credit. The baseline of 3 applies because the schema fully carries the parameter documentation burden.

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

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

The description clearly states the tool's purpose: route factual questions to a large set of authoritative data sources and return a structured answer with citations. It provides many concrete domains and examples. However, it does not explicitly differentiate ask_pipeworx from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it is clear but not fully sibling-distinguishing.

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: prefer this over web search, use it for factual questions even when web search could answer, and start here for most questions. It also names a concrete alternative, deep_research, for broad/multi-part questions, which is exactly the kind of when-to-use vs. when-not-to-use guidance an agent needs.

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

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

The description goes well beyond the annotations by disclosing the experimental status, the live candidate mechanism, the current state (no candidate active, retired on a specific date), and the fact that it does not fall back to anything else. With annotations already providing read-only/idempotent hints, this is exemplary transparency.

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

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

The description is front-loaded with the core identity and the current-candidate status, and every sentence contributes a distinct piece of information (what it is, current state, how to use, fallback assurance). It is slightly dense with details like the exact retirement date, but still well-structured and appropriately sized.

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 wrapper around ask_pipeworx, the description is complete enough to support invocation: it states it is a full working router, that input is a question, and that behavior currently matches ask_pipeworx. The response shape is referenced but not described, and without an output schema the agent must rely on the sibling definition, so it is not fully self-contained.

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

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

Schema description coverage is 100%, with every parameter documented as an alias for 'question', so the schema already carries the semantic weight. The description only says 'same arguments' without adding any details about format or behavior, so it meets the baseline but adds no extra meaning.

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

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

The description identifies the tool as a beta version of ask_pipeworx, a universal router over 5,798 tools, and clearly distinguishes it from the stable sibling by noting it may carry candidate routing improvements. However, it relies on the ask_pipeworx sibling to convey the core function (answering natural-language questions), so it is clear but not fully self-contained.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. The when-to-use guidance is clear, though it does not explicitly state 'use ask_pipeworx when you need the stable production version' — that exclusion is implied rather than stated.

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

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

The annotations already declare the operation is read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond that: exact success return shape, explicit refusal reasons, reliance on verbatim evidence, and the extra LLM call cost. This fully discloses how the tool behaves when data is insufficient.

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 section earns its place: mode definition, routing behavior, return contract, refusal conditions, use cases, and cost trade-off. It is front-loaded with the most important decision signal ('hallucination-resistant ... high-stakes reads') and remains structured rather than rambling.

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

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

With no output schema, the description fully specifies success and refusal return shapes, including refusal reasons. It also explains when this tool is preferable, what distinguishes it from the sibling, and the cost trade-off. An agent has enough context to invoke it correctly and interpret its result.

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%, meaning the question parameter and its aliases are fully documented in the input schema. The description does not add parameter-level details beyond that, which is acceptable but not additive. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description names a specific mode ('hallucination-resistant answer mode'), a clear resource (ask_pipeworx_grounded), and a distinct behavior: extracting answers only from tool results. It explicitly contrasts with the sibling ask_pipeworx, so an agent can tell them apart without opening schemas.

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

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

It gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts. It also gives a when-not-to-use directive: prefer ask_pipeworx for casual lookups, because this mode costs an extra LLM call.

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?

The description discloses a great deal beyond the annotations: output shape (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), the explicit gaps[] behavior, contradictions[], semantic excerpting, latency expectations (15-60s, up to ~90s), and account/paid-tier requirements. The annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with this and are reinforced rather than contradicted.

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 appropriately so for a complex tool with no output schema. It front-loads the critical account requirement and use-case routing, then moves into deeper mechanics. Some sentences are dense and slightly repetitive with the schema, but every sentence serves a practical purpose.

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

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

Since there is no output schema, the description carries full responsibility for explaining return values. It does this thoroughly: findings packet fields, citation_uri resolvability, gaps[] for unanswered facets, contradictions[] for standard/thorough, latency, auth requirements, and alternatives. Nothing critical is missing for an agent to select and use this tool correctly.

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

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

Schema description coverage is 100%, and the depth parameter's enum semantics are already thoroughly documented in the schema, including the paid nature of 'thorough' and the contradiction/gap-recovery behavior. The tool description largely restates these details rather than adding substantial new parameter-level meaning, so the high-coverage baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's action ('Grounded multi-source research'), its resource ('Pipeworx's 1517 STRUCTURED data sources'), and its mechanism (decomposes question into facets, routes to tools in parallel). It also distinguishes itself from open-web search and explicitly names ask_pipeworx as the alternative for single lookups, so sibling differentiation is strong.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples. It also states clear when-not-to-use conditions: 'For a single lookup use ask_pipeworx instead' and 'If you are not signed in, use ask_pipeworx instead'. This is excellent routing guidance.

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

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

Annotations already declare readOnlyHint, 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 already indicate readOnly, idempotent, and non-destructive, but the description goes well beyond that: it discloses the full fan-out across SEC, XBRL, USPTO, USAspending, FDA, DOL, GDELT, and GLEIF; the USPTO sunset soft-fail; the 'empty section is real no-data' behavior; and the resolved:false private-company behavior. This is rich behavioral context that annotations could not provide.

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

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

The description is long but information-dense; nearly every sentence covers a source, behavior, or edge case needed for correct invocation. It is front-loaded with user-intent examples and the 'ALWAYS PREFER' guidance, though bullet points or section breaks would improve scanability.

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

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

There is no output schema, so the description carries the full burden of explaining return semantics. It does so thoroughly: cik, company_name, recent_filings with URIs, fundamentals sort order, patents, federal contracts, fda_products caveat, hiring data, news fallback, LEI, and sources_used/sources_failed. For a complex, source-fanning tool, this is complete enough to invoke and interpret correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable nuance: tickers, zero-padded CIKs, and company names are all accepted; 'type' values behave interchangeably; names resolve via SEC EDGAR; and 'resolved_from/resolved_to' clarify CIK resolution. These details enhance the schema's descriptions.

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

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

The description clearly states it builds a 'full cross-source profile of a US public company in ONE parallel call' and anchors this with concrete user phrasings like 'Tell me about X' and 'give me the rundown on $TICKER.' It also contrasts itself with chaining single-pack lookups, making its scope and resource easy to distinguish.

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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is an explicit usage trigger. It also explains edge cases like private companies and expected empty sections. However, it does not provide guidance on when to choose sibling tools like deep_research or compare_entities 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 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?

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds substantial behavioral context: warnings can appear even with matched_pairs>0, spreads are gross of Kalshi fees, unclassified legs are never paired, and temporal_alignment null means unknown rather than aligned. This goes far beyond what annotations or schema provide.

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

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

The description is long, but nearly every sentence carries a distinct behavioral or situational fact, and it is front-loaded with purpose before diving into modes and return fields. It is structured with clear labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. Minor redundancy exists around temporal_alignment and repeated flag lists, so it is not maximally concise.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. An agent has enough information to interpret results correctly without guessing.

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

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

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds valuable semantics about parameter interaction: explicit params override the topic-mapped side, and both modes run the identical token-overlap matcher. That extra meaning justifies a 4.

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

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

The description opens with a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two modes, pre-mapped topics and explicit tickers/slugs, further pin down exactly what operation the tool performs. This specificity clearly separates it from siblings like polymarket_arbitrage even without naming them.

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

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

The description clearly explains when to use each mode: topic shortcuts for macro events, explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also cautions that pre-mapped topics often return compatibility_warning and are not tradeable. It does not explicitly name alternatives among siblings, 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?

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 readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: it explains multi-source cascading, ambiguous-match behavior returning figi_candidates, explicit unresolved fields, ISIN-to-LEI mapping, and graceful degradation when GLEIF/OpenFIGI are down. This is unusually transparent for a tool with no output schema.

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

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

The description is long and dense, with heavy parentheticals, but it front-loads the purpose and the critical 'Use FIRST' guidance. For the complexity of the tool and the absence of an output schema, most sentences carry useful information; the structure could be improved with clearer separation between the company and drug cases, but it is not bloated.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers supported inputs, sources, ambiguous matches, unresolved identifiers, return fields like figi_candidates and unresolved, and failure behavior. An agent has enough context to decide when to call it and what to expect back.

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 crucial meaning that the schema alone lacks. It explains exactly what 'value' should contain, distinguishes ticker/CIK/name vs. brand/generic, and gives a concrete warning about bond issuer names with the 'NEW YORK ST DORM AUTH' example. It also enriches the 'type' parameter by explaining what each type resolves and from which sources.

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 plus resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also names the supported types and contrasts with siblings by making clear it is the name-to-ID lookup tool, not a profile or comparison 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 explicitly says 'Use FIRST whenever you have a name but need an ID,' which routes the agent clearly. It also notes that this tool replaces 2-3 manual lookups, but it does not explicitly state when to use profile/compare siblings once an ID is already in hand, so it slightly misses a full when-not usage set.

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

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

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.