Repology

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context beyond annotations: the default model (Workers AI Llama-3.3-70b), the BYO key arrangement for Anthropic, and the cost implications. It also discloses the return structure, which helps the agent understand what to expect.

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 efficiently structured: it opens with the core action, then covers defaults/cost, return shape, and use cases. No filler or repetition; every sentence earns its place. The front-loaded information is immediately actionable.

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

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

Despite no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view). It addresses the 'why' with use cases and the 'how' with parameter dependencies. For a read-only probe tool, this is complete and self-sufficient.

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 semantic context by explaining the relationship between models and _apiKey (pass _apiKey to also probe Anthropic) and clarifying defaults. This goes slightly beyond the schema's field descriptions.

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

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

The description uses a specific verb ('Probe') and resource ('one or more LLMs') with clear scope: scoring visibility of a business/brand/product/topic. It also distinguishes itself from siblings by focusing on AI visibility scoring, which is distinct from ask_pipeworx or competitive scanning tools.

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

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

The description clearly states when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context on model selection and cost implications. It lacks explicit exclusions or alternatives, but the guidance is sufficient for an AI agent to decide when to invoke it.

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

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

Annotations already declare readOnly, openWorld, idempotent, destructive=false, so the description does not carry the safety burden. It adds valuable behavioral detail beyond any annotation: resource routing, filling arguments, and return format ('structured answer with pipeworx:// citation URIs'). It does not reveal potential failure modes, latency, or what happens when no tool matches, but the overall behavior is well-outlined.

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 heavily front-loaded with the key 'prefer over web search' message, and the examples are useful for grounding the question format. But the paragraph repeats the idea 'even if web search could also answer it' in close proximity, includes a long-list of source domains, and ends with an incomplete sentence ('unless...'), which hurts the coherence. It is not as crisp as the best tool descriptions.

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 schema is trivial (one required parameter) and annotations already cover the safety model, the description does cover the main contextual pieces: when to use, what kind of inputs, what kind of output, and what makes this tool special among broader web-search alternatives. The main deficiency is the discarded psychological 'domain' — the actual 'START HERE' language with a dangling exception — so without that it would be a 5.

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

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

Schema description coverage is 100%: all six parameters are explicitly documented as aliases for the single 'question' parameter, and the schema includes examples. The tool description's example queries reinforce natural-language usage but do not introduce new semantic constraints (length, language, formatting, disambiguation). Per the rubric, with high schema coverage, the description does not need to compensate if it remains neutral, which is the case here.

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

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

The description clearly identifies the tool as a natural-language router for authoritative structured data: it 'routes the question to the right one of 5,596 tools across 1465 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It is also anchored to a clear use-case, 'prefer over web search' for factual/current/historical data. However, it never distinguishes itself from the similarly named siblings ask_pipeworx_beta and ask_pipeworx_grounded, so the selector agent still has ambiguity and the score is capped below 5.

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 strongly instructs when to use: 'PREFER OVER WEB SEARCH for questions about...', 'Use whenever...', and 'START HERE: most questions' followed by concrete example queries. It also implies the alternative is web search. But it does not explicitly say when NOT to use this tool or how to choose between ask_pipeworx_beta and ask_pipeworx_grounded, and the trailing 'unless...' fragment is incomplete — a missed opportunity for 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, openWorld, idempotent, and non-destructive annotations, the description provides useful live-state context: no candidate is active right now, so this currently behaves identically to ask_pipeworx. It also disambiguates 'falls back to nothing' by explaining that it is itself a full working router, which is important operational nuance.

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?

It is reasonably concise: the first sentence defines the tool, the second gives current state, and the third gives usage guidance. The level of detail about the currently retired candidate may be temporary, but it currently earns its place for agent decision-making.

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 accurately points to ask_pipeworx for identical behavior and response shape, which is adequate since that stable sibling is in the same tool list. It could be more complete by naming the exact returned answer format, but for a beta mirror of an existing tool the coverage is sufficient.

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 six parameters at 100%, clearly describing that q, text, input, query, and prompt are aliases for question. The description only adds 'same arguments,' which does not supplement the schema meaningfully, 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 identifies the tool as a beta of ask_pipeworx, a universal router with the same 5,596 tools and response shape, and clarifies it is a full working router rather than a thin fallback. It does not separately define the base routing behavior, but the name, sibling set, and comparison to ask_pipeworx make the purpose clear enough.

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 recommends using it exactly like ask_pipeworx when the agent wants the newest routing, and says results are compared against the stable router. It doesn't say when not to use it, but 'beta' and 'experimental edge' carry that implication.

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, idempotent, and non-destructive hints, the description adds important behavioral context: it will not invent facts, it extracts only from tool results, refusal reasons are enumerated, and it costs an extra LLM call. No contradiction with annotations exists.

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

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

The description is dense but well-structured: it leads with the core value proposition, explains routing and behavior, provides a concise success/refusal contract, and ends with usage guidance and cost comparison. Every sentence adds decision-relevant information without fluff.

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

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

Given there is no output schema, the description compensates by fully specifying both the success shape and the refusal shape. Combined with rich annotations and a detailed input schema, an agent has enough context to select and invoke the tool correctly for high-stakes use cases.

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 input schema fully documents the single required parameter and its aliases. The description does not add parameter-level meaning beyond saying an answer will be extracted from tool results, which is appropriate given the high schema coverage. 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 capability: a hallucination-resistant grounded answer mode that routes through the same pipeline as ask_pipeworx and extracts answers strictly from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing refusal behavior and evidence-based answers.

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

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

The description states exactly when to use this tool: whenever an answer will be quoted, cited, or acted on, especially in high-stakes domains such as financial, legal, medical, or public statements. It also gives an explicit alternative condition: prefer ask_pipeworx for casual lookups because grounded 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 extensively discloses behavioral traits beyond the annotations: it explains fan-out logic, resolver contract (market_match_confidence, alternatives), parent_event extraction, news fallback behavior, safety short-circuiting for low-confidence matches, closed market handling, wide-spread market flags, and resolution-rule risk analysis. This goes far beyond what annotations provide.

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

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

The description is long and dense, but it is well-structured with capitalized section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and each section conveys critical operational detail. While not concise in length, it is efficiently organized and avoids fluff, making the structure effective for a complex tool.

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

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

With no output schema, the description fully compensates by detailing the response shapes (result.market, result.analysis, result.evidence), resolver confidence fields, parent_event structure, news fallback fields, and edge cases (low-confidence match, closed markets, wide spreads, cancellation rules). This is complete for a tool of this complexity, leaving few operational ambiguities.

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

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

The input schema already provides 100% coverage with detailed descriptions for 'market', 'depth', and 'include_raw'. The description adds little new parameter-specific semantics—it restates the market input formats and mentions fan-out examples that relate to depth, but does not clarify any parameter beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific action ('Research a Polymarket bet by pulling the relevant Pipeworx data'), clearly states the input types (slug, URL, question text), and describes the output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools by focusing on Polymarket betting research and the fan-out mechanism, which is unique.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This tells the agent when to invoke the tool. It does not explicitly mention when NOT to use it or name alternatives, but the context is clear enough for 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?

Annotations already declare the tool as read-only and idempotent. The description goes further by disclosing data sources (SEC EDGAR/XBRL, FAERS), specific metrics (revenue, net income, adverse-event counts), handling of off-calendar fiscal years, and result sorting behavior. This is rich context beyond what annotations provide.

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

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

The description is dense with information but well-structured and front-loaded with query examples. Every sentence adds value—no filler or repetition. Despite its length, it remains efficiently organized and easy to parse.

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

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

Given no output schema, the description thoroughly explains return behavior (paired data, citation URIs, sorting by primary metric). It covers both entity types, data sources, and the tool's efficiency advantage, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% but the description adds substantial meaning: it explains what each 'type' value does, what data is retrieved for company vs drug, and how 'values' should be formatted (tickers/CIKs for companies, names for drugs). This significantly enhances parameter understanding beyond the schema descriptions.

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

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

The description clearly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It uses a specific verb ('compare') and resource ('entities'), and distinguishes itself from sequential single-pack lookups, making its purpose unmistakable.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives concrete query examples and specifies the conditions (comparing 2–5 entities) under which the tool should be used, effectively communicating when to use it over alternatives.

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

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

Beyond the annotations, the description discloses important behavioral traits: it requires an account, thorough depth is paid, results may take 15-90 seconds, findings include gaps rather than invented answers, citations are stable and fetchable, and it returns contradictions and hop metadata. This is substantial behavioral context that the annotations alone do not carry.

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 runs long, occasionally with run-on clauses, but every sentence contributes unique information — auth, routing, data source scope, output shape, gap behavior, timing, and depth semantics. It front-loads the critical account requirement and comparison to ask_pipeworx, which helps an agent route immediately.

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 fully compensates by describing the return payload: findings with verbatim evidence, confidence, source, fetched_at, citation URI, contradictions, and gaps. It also covers intended use cases, auth, latency, alternative tools, and depth semantics, leaving no meaningful gap for invoking the tool correctly.

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

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

Both parameters are already fully documented in the schema (100% coverage), so the baseline is 3. The description adds useful nuance by explaining that depth changes the number of facets, introduces gap-recovery passes, implies the paid requirement for thorough, and gives example natural-language questions for the 'question' parameter.

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

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

The description clearly identifies a specific action — grounded multi-source structured-data research — and a distinct resource (Pipeworx's 1,465 structured data sources). It explicitly contrasts with open-web search and routes single-lookup questions to ask_pipeworx, so an agent can select it correctly without inferring.

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, and explicit when-not-to-use guidance: prefer ask_pipeworx for single lookups or breaking/colloquial live-news topics. It also states the account requirement and names the fallback tool if the user is not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and then provides usage context, return value details, and invocation guidance. It is somewhat long due to the domain list, but each sentence earns its place and the structure is clear and 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?

The tool has no output schema, but the description explains what is returned (top-N tools with schemas). It also gives invocation context (call first) and covers the main parameter (query). It could mention potential errors or edge cases, but for a discovery tool it is sufficiently 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 schema fully describes each parameter. The description adds no additional parameter-level meaning beyond what is in the schema, but it does provide example queries in the schema. This is at the baseline for full 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself as a meta-tool for discovering other tools, which sets it apart from siblings like 'search_within' or 'problems'.

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

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

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly indicates when to use it versus other 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral detail: fans out across multiple sources, returns up to 5 filings, patents API sunset with soft-fail, and GDELT→GNews fallback. This goes beyond annotations without contradicting them.

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

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

The description is a single dense paragraph but is well front-loaded with example queries and core purpose. While long, every sentence carries actionable information (fallbacks, limitations, output specifics). It earns its length.

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

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

No output schema exists, so the description must cover return values. It enumerates the key fields (cik, filings, fundamentals, patents, news, LEI) and notes the patents soft-fail. Given the tool's complexity, this is sufficient for an agent to set expectations.

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

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

Schema coverage is 100% and the description essentially restates the schema's param info (ticker/CIK, names not supported). It adds no new meaning, so the baseline of 3 applies.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company in ONE parallel call' and lists the specific output categories (CIK, filings, fundamentals, patents, news, LEI). It also distinguishes itself from chaining single-pack lookups, making the purpose unambiguous and distinct from siblings.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it (names not supported, use resolve_entity first), giving clear decision criteria.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate them. It adds useful behavioral context about clearing sensitive data and tying deletion to stale context, exceeding the baseline set by annotations.

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

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

Two tight sentences, front-loaded with the action and resource, then usage context and sibling references. No filler or redundancy.

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

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

For a single-parameter delete tool with strong annotations and no output schema, the description covers what, when, and how it relates to sibling tools. Complete for its simplicity and context signals.

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, including clear description 'Memory key to delete'. The tool description adds no additional parameter semantics beyond implying the key identifies a stored memory, so baseline 3 is appropriate.

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

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

Description uses specific verb 'Delete' and resource 'previously stored memory by key'. It clearly distinguishes from siblings by referencing 'Pair with remember and recall', making the tool's unique role in the memory lifecycle explicit.

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

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

Provides explicit when-to-use guidance: 'context is stale, the task is done, or you want to clear sensitive data'. Names alternatives (remember, recall) for related operations, fulfilling the 'alternatives' criterion for a high score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description adds valuable context by explaining the underlying behavior: 'Fetches the page', extracts title/description/key links, and emits a standard markdown blob. This goes beyond the safety annotations to describe the pipeline and output format.

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

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

The description is three sentences, front-loaded with the main purpose. It efficiently states the process and then lists useful scenarios. No wasted words; every sentence contributes to understanding the tool.

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

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

Despite having no output schema, the description clearly states the output is a 'single text blob ready to drop at site-root/llms.txt' in standard markdown format. It also mentions the main use cases. It lacks edge-case handling (e.g., invalid URLs) but is complete for this simple, well-annotated tool.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description does not add meaningful parameter semantics beyond what the schema provides; it only reiterates 'any URL' and the general concept of links. 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 the specific verb 'generate' with the resource 'llms.txt file for any URL', and clearly outlines the process (fetch, extract, emit). It distinguishes this tool from all siblings by focusing on the generation of standard llms.txt markdown, which no other sibling tool does.

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

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

The description includes a 'Useful for' list that gives clear context on when to use it (indexing clients' sites, drafting own llms.txt, auditing competitors). However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description goes beyond annotations by revealing the output structure (id, type, params, created_at, last_fired_at, fire_count) and the default behavior (only active subscriptions unless include_inactive). This adds useful behavioral context about what the caller will see and how the include_inactive parameter affects the result.

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: the first states the action and return fields, the second gives usage context. Every word earns its place, and it is front-loaded with the core purpose. There is no fluff or redundancy, making it highly efficient for an agent 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?

Given the low complexity (one optional parameter), strong annotations, and absence of an output schema, the description compensates well by enumerating the return fields. It also provides situational context (when to use) and notes the active-by-default behavior. This is sufficient for an agent to understand what the tool does, what it returns, and when to invoke it without needing additional information.

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

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

The only parameter (include_inactive) has a complete schema description, so the schema already covers its meaning. The tool description adds minimal extra value by implying the default (active only) via the term 'active subscriptions,' but it doesn't elaborate on the parameter's effect. With 100% schema coverage, the baseline of 3 applies, and the description does not meaningfully exceed it.

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

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

The description clearly states the action: 'List the caller's active subscriptions.' It specifies the resource (subscriptions) and scope (caller's active), and lists the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by being the read-only listing tool, and it even mentions finding an id to cancel, which ties to unsubscribe but keeps the listing purpose distinct.

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 use the tool (before adding subscriptions, when seeking a cancel id). It implies that canceling itself is done elsewhere (via unsubscribe), but it doesn't name the alternative tool explicitly, so it misses the full 'when-not' clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description does not need to restate these. It adds the detail that the identifier is canonical and often an email, but it omits any additional behavioral traits like output format, pagination, or potential error conditions. This is adequate but not rich.

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 sentence with no wasted words. It front-loads the tool's purpose and immediately specifies the input key and format, making it easy to parse and act upon.

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 lookup tool with a rich output schema and clear annotations, the description is mostly sufficient. It tells the agent what input to provide and what kind of data will be returned. It does not explicitly address potential edge cases or relationships to sibling tools, but the available schema and context fill most gaps.

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

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

Schema coverage is 0%, so the description carries the parameter-documentation burden. It explains that the 'maintainer' parameter is a 'canonical maintainer id (often email)', which adds meaning beyond the parameter name. The schema examples reinforce this, but the description itself provides essential clarification.

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 that the tool provides a 'Maintainer summary' keyed by 'canonical maintainer id (often email)', which clearly identifies the resource and input. It does not use an explicit verb like 'retrieves' or 'returns', but the meaning is unambiguous enough to distinguish it from sibling tools like entity_profile or project.

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 that this tool is used when you have a canonical maintainer ID, but it does not explicitly state when to prefer it over alternatives or mention any exclusions. There is no naming of sibling tools or a when-not-to-use clause, so the guidance is implied rather than explicit.

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 are all false, indicating a mutating/non-idempotent operation, but the description adds substantial behavioral context beyond that: rate-limiting ('Rate-limited to 5 per identifier per day'), cost implications ('Free; doesn't count against your tool-call quota'), the claim_token flow for anonymous submissions, and how feedback is processed ('team reads digests daily and signal directly affects roadmap'). This fully discloses side effects and expectations.

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

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

The description is a dense paragraph, but every sentence earns its place: purpose, use cases, exclusions, claim-token mechanics, rate limits, and quotas. It is front-loaded with the core action ('Tell the Pipeworx team something is broken...') and organized logically. Despite its length, there is 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?

For a tool with 4 parameters (including a nested object), no output schema, and complex feedback semantics, the description is exceptionally complete. It covers anonymous submission, the claim-token retrieval workflow, rate limits, cost, and scope boundaries. An agent given this description will know exactly when and how to invoke the tool, and what to expect in return.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds meaningful extra semantics: clarifies the claim_token usage with an example call syntax (pipeworx_feedback({claim_token:"pwfb_…"})), explains that filing without an account returns a claim_token, and instructs users to describe issues in terms of Pipeworx tools rather than pasting end-user prompts. This goes beyond the schema and enhances usability.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the feedback categories (bug, feature, data_gap, praise) and explicitly scopes it to tools served by this Pipeworx connection, distinguishing it from any sibling tools (none of which are feedback-related).

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 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 an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead,' plus a decision rule for identifying Pipeworx tools. This is a model of usage guidance.

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

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

Annotations already cover read-only/idempotent behavior; the description adds valuable detail about caching ('Cached 5min-1h'), privacy ('no PII'), and data provenance ('derived from CF analytics-engine'). This goes beyond the structured 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 front-loads the core result, then gives use cases, then data-source/caching details. All sentences contribute value; it's slightly longer than strictly necessary but remains focused and well-ordered.

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-optional-param tool with no output schema, the description explains outputs, cache behavior, privacy, and intended uses. Minor ambiguity remains around what 'packs' means, but overall it's sufficiently complete for reliable invocation.

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

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

Schema coverage is 100%, including the enum values and the default behavior (24h). The description mentions the window but doesn't add additional parameter semantics beyond what the schema already documents.

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 resource ('top tools, top packs, and total call volume') and the scope ('what other AI agents are calling on Pipeworx right now'). It distinguishes this trending tool from siblings like discover_tools by emphasizing aggregated usage signal rather than generic discovery.

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

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

Three concrete use cases are provided: finding hot data sources, confirming canonical tool selection, and checking alignment with other agents' needs. It lacks explicit alternatives or when-not-to-use guidance, but the context is clear enough to guide invocation.

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 goes further by disclosing the fill check logic, threshold tolerances (deviations >3pp, >20% placeholder fraction, >=0.30 Jaccard), and the explicit warning 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it.' This provides rich behavioral context beyond what annotations can convey, with 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?

While lengthy, every sentence earns its place. The description uses clear subheadings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to organize dense technical details. It front-loads the core purpose and mode selection, then adds edge-case behavior and response shape in a structured manner, making it easy for an agent to parse.

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

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

Given the tool's complexity (two modes, filtering logic, live book assessment) and the absence of an output schema, the description compensates thoroughly by describing the response structure (opportunities[], partition_check fields), explaining edge-case handling, and providing actionable trade guidance. No critical aspect is left unspecified.

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

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

Although the schema already documents both parameters (100% coverage), the description adds substantial meaning: for 'event' it gives example slugs and notes full URLs are accepted; for 'topic' it explains the seed question style and details what happens in cross-event mode. It also clarifies that both are optional, showing which mode each parameter activates.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection methods, and it explains three invocation modes (no-arg trending_scan, event, topic), making the tool's scope 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?

Explicitly provides when-to-use guidance: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It even recommends event for a specific market and names an alternative tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This goes beyond baseline guidance by giving conditional choices and exclusions.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: edge is net of slippage, there is a 24h-move warning, Fed candidates are excluded due to unreliable signal, placeholder-slug filters drop certain markets, and the response includes diagnostics explaining empty segments. No contradiction.

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

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

The description is long but well-structured with distinct sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and the core purpose is front-loaded. Every sentence carries substance, though the density and ALL-CAPS style make it slightly overstuffed.

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

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

Since there is no output schema, the description fully compensates by detailing the response shape (by_segment, fed_candidates, _diagnostics), filtering semantics, and why segments may be empty. It also covers caching and the Fed signal caveat, making it complete for an agent 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 covers 100% of parameters, but the description's 'TRADEABLE-EDGE KNOBS' section adds meaning beyond schema: min_partition_leg_kelly applies per-leg because partition arbs return kelly_fraction_half=0 at parent level; min_liquidity/max_spread_pp drop unrealizable edges. This goes well beyond the 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 clearly distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_kalshi_spread by focusing on Pipeworx-vs-market edge detection and enumerating model families.

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

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

The phrase 'Built for "what should I bet on today"' provides an explicit use case, and the description explains when tradeable-edge knobs like min_liquidity and max_spread_pp are relevant. It doesn't name alternatives or exclusions, but the intended scenario is clear enough.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds substantial behavioral context: history bounded by 60-day TTL, snapshots written on cache-miss, decay computed from daily closes not intraday, and interpretation of expired opportunities. This goes well beyond the structured fields.

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

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

The description is dense but well-organized with sections for RESPONSE and LIMITS. Every sentence provides functional value—explaining output structure, data gaps, and interpretation nuances. No filler or redundancy.

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

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

Given the tool's complexity and absence of an output schema, the description fully compensates by detailing the response shape (tracked, expired, snapshot_dates), semantics (trend, decay), and limitations (TTL, cache-miss gaps). It is complete for an agent to understand what the tool returns and how to interpret 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?

Schema coverage is 100%, with both parameters described. The description repeats defaults and adds minor context like 'snapshot family' but does not fundamentally enhance understanding beyond what the input schema already provides. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) by focusing on historical persistence and decay.

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: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It implies when to use this tool (to assess edge longevity) and contrasts with alternatives via the reference to polymarket_edges, but does not explicitly name an alternative or state 'when not to use.'

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds rich context: mode requirements, default behaviors, key outputs, and the specific risk that partial basket fills convert an arb into an unhedged directional position. 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 long but structured: purpose, mode breakdowns, return values, usage directives. Every sentence adds value. It is dense and could be considered overwhelming, but given the tool's two-mode complexity, the length is justified.

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

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

The description is complete for a complex tool. It covers both modes, parameter semantics, return fields, risk warnings, and when to use it. The lack of an output schema is compensated by listing the returned fields in detail.

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 goes far beyond it by explaining parameter semantics in context: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional — shares per leg' in basket mode; side has mode-specific defaults and meanings.

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

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

The description opens with a clear, specific verb phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill-risk validation rather than edge detection or signal generation.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also clarifies when to use single-market mode vs basket mode, and explains the risk of partial fills.

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

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

The description goes far beyond the annotations (readOnly, idempotent, non-destructive) by detailing compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the nuanced warning that matched_pairs=0 can mean different things depending on other fields. This level of behavioral disclosure is exceptional and helps the agent interpret results correctly. 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 it is well-organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core definition. Every sentence contributes critical information, and the length is justified by the tool's complexity. However, it is not 'two sentences' and could potentially be streamlined, so it stops short of 5.

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

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

With no output schema, the description fully covers response structure (leg prices, spread values) and safety/edge-case fields (compatibility_warning, temporal_alignment, skipped counters). It also explains when the output is meaningless (aligned:false, incompatible bet shapes) and includes practical caveats about market reality. This is complete for a complex tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that the `topic` parameter auto-fetches matching events on both venues, and that explicit ticker parameters override the topic mapping. It also clarifies the relationship between parameters (custom pairing). This goes beyond the schema's bare field descriptions, earning 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 precise verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly identifies the tool's purpose and distinguishes it from sibling tools like polymarket_arbitrage (which likely focuses on intra-venue or separate cross-venue activity) and polymarket_edges. The explicit mention of computing a spread between two specific venues leaves no ambiguity.

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

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

The description explains two modes of operation (topic shortcuts vs explicit tickers) and gives context about when spreads are meaningful ('when the bet shapes are equivalent...'). It also warns that most pre-mapped topics currently return compatibility_warning, which guides appropriate expectations. However, it does not explicitly name alternative tools or state 'use this instead of X' scenarios, so it misses the 'alternatives' part of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small behavioral nuance with 'outstanding' (implying a filter for unresolved problems) but does not disclose other traits like pagination, sorting, or whether problems are returned in a specific order. This aligns with the annotations, with no contradiction.

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

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

The description is a single short sentence, immediately conveying the core purpose. There is no wasted text, and the wording is front-loaded with the key noun phrase. It earns full marks for conciseness and clear structure.

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 one parameter and an output schema, the description still leaves significant gaps. It does not clarify what counts as 'outstanding', whether the result is a list, or how it relates to sibling tools like 'recent_changes' or 'maintainer'. The description is too minimal to fully equip an agent to decide when and how to invoke this tool.

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

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

Schema description coverage is 0%, and the description only states 'for a project', which adds little beyond the parameter name 'project'. The examples in the schema ('firefox', 'nginx') hint at project names, but the description does not explain what format or identifier is expected. With low schema coverage, the description should provide more meaningful guidance, but it does not.

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

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

The description names the resource ('outstanding maintenance problems') and its scope ('for a project'), making the tool's purpose identifiable. However, it lacks a verb like 'Get' or 'List', so it reads as a noun phrase rather than an explicit action. It distinguishes from siblings by the unique 'problems' resource, since no other tool mentions maintenance problems.

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 no information about when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or related sibling tools. Usage must be inferred solely from the tool name and brief noun phrase, which is insufficient for clear selection guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context, such as 'per-repo' grouping, but does not disclose expected output structure or edge cases. This is adequate but not rich.

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, concise sentence that immediately conveys the tool's purpose. No filler or redundant rephrasing; it earns its place.

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

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

The tool is simple (one parameter), has full annotation coverage for safety, and includes an output schema. The description provides the core purpose and enough context to understand the input. It could add more detail about per-repo grouping, but the presence of an output schema and annotations reduce the need.

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 only defines 'name' as a string with examples, providing no description (0% coverage). The description compensates by explaining that the parameter is a project name and giving a concrete example, making the parameter semantics clear enough for a single-parameter tool.

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

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

The description states the tool returns all packages per-repo for a given project name (e.g., 'firefox'). It identifies the resource (packages) and the lookup key (project name), but lacks an explicit verb and does not distinguish from sibling tools like projects_search or repositories.

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 about when to use this tool instead of related tools such as projects_search or repositories. The description only implies a use case by example, but does not state exclusions or alternatives.

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

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

Annotations already provide safety and idempotency hints. The description adds valuable behavioral context by noting the 200-project page limit, the per-repo version data in the response, and the pagination concept (start_name/end_name). This goes beyond what annotations convey, though it does not detail pagination mechanics fully.

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, information-dense sentence that front-loads the action and resource, lists filters concisely, and specifies the output limit and content. Every word earns its place with no repetition or filler.

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

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

Given the existence of an output schema and comprehensive annotations, the description covers the essential functionality: filtering, pagination, and return data. It does not explain pagination cursor usage or edge cases, but those are partially documented in the input schema, so the description is adequate 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 75% with 'category' and 'maintainer' lacking descriptions, but the description mentions these as filter types, compensating for that gap. It also clarifies the meaning of 'count' implicitly through the 200-per-page limit and the return format, adding value beyond the schema fields.

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

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

The description starts with specific verbs 'Paginate or filter' and identifies the resource (Repology projects) along with the filtering criteria (name substring, maintainer, category, repository membership). It clearly distinguishes this from sibling tools like 'project' (singular) by focusing on search/pagination over multiple projects.

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 implies when to use the tool (for searching/filtering projects) but does not explicitly mention alternatives or exclusion conditions. There is no 'use this instead of X' guidance, which would help an agent choose among siblings like 'maintainer' or 'project'.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals the key-omission behavior (listing all keys) and the scoping mechanism (anonymous IP, BYO key hash, or account ID), which are not present in the structured data. No contradiction with annotations.

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

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

The description is three sentences, with the primary action stated up front. Every sentence adds value: functionality, use cases, and scoping/companion tools. No filler or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, behavior, and caveats (scoping). It also correctly frames the tool's role within the remember/forget ecosystem, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with a description for the key parameter. The tool description adds semantics by explaining that omitting the key lists all saved keys, which is beyond the schema's simple 'retrieve' phrasing. However, it doesn't provide examples or constraints beyond the schema's existing examples, so it falls short of a 5.

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

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

The description clearly specifies the two main actions: retrieving a saved value and listing all keys when the key argument is omitted. It explicitly names the related tools (remember, forget) which distinguishes it from siblings.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names alternatives: 'Pair with remember to save, forget to delete,' clearly delineating when to use sibling tools.

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

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

The annotations declare readOnlyHint=true, but the description explicitly says 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect. This directly contradicts the read-only annotation, requiring a score of 1 and a contradiction flag.

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 only three sentences and front-loads the primary action and return type. Every sentence adds value: return payload composition, filtering options, mark_read side effect, and endpoint alternative. There is no redundancy or fluff.

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

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

Given five optional parameters and no output schema, the description still conveys the return payload structure (source, citation_uri, raw event payload), filtering behavior, the mark_read side effect, polling suitability, and an alternative access URL. This is thorough for an agent to invoke the tool correctly.

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

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

All 5 parameters are documented in the schema (100% coverage), but the description adds meaningful detail: gives an example type ('sec_8k'), clarifies that since is an ISO timestamp, and explains the behavioral impact of mark_read. This goes beyond the schema, though it doesn't elaborate on limit or unread_only further.

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

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

The description clearly states what the tool does: 'Pull fired events from your subscription feed. Returns the most recent alerts...' with a specific verb and resource. It also distinguishes itself from subscription management siblings by focusing on retrieving alert events rather than managing subscriptions.

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

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

It provides useful usage context: 'Polls work fine' and offers an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly compare against sibling tools or say when to prefer this tool over alternatives like list_subscriptions, so it misses some 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 declare readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds essential behavioral context: it fans out to multiple sources in a single parallel call, explains the GDELT→GNews fallback, notes the USPTO PatentsView API sunset, and specifies the return shape (changes[] grouped by source, total_changes, citation URIs). This goes far beyond the structured annotations.

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

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

The description is dense but well-organized, front-loading with user intent phrases before diving into technical specifics. Every sentence contributes: purpose, source breakdown, fallback behavior, parameter format, return structure, and sibling differentiation. No filler or redundancy.

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

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

Given the tool's complexity (multiple upstream APIs, fallback chains, soft-fail conditions) and absence of an output schema, the description is remarkably complete. It explains return structure, source grouping, citation URIs, and the `since` format. Annotations cover idempotency and read-only safety, so the agent has enough context to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter understanding by giving concrete examples (ISO date vs '7d' shorthand) and recommending '30d' or '1m' for typical monitoring. The value parameter is also clarified with ticker or zero-padded CIK examples, which adds practical guidance over the schema alone.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with concrete user-intent examples ("What's new with X"). It explicitly distinguishes itself from the sibling entity_profile, which returns a static profile. The verb+resource+scope is specific: "change feed for a company in the last N days/weeks/months."

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 context (when to query recent changes) and directs users to entity_profile when they want the static profile regardless of window. It also discloses fallback behavior (GDELT→GNews, USPTO soft-fail) so the agent knows when results may be incomplete.

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

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

Annotations already convey safety (readOnly=false, destructive=false, idempotent=true). The description adds meaningful behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier,' 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This discloses persistence semantics, scope, and TTL—valuable for the agent. It does not explicitly state overwrite behavior, but the idempotentHint covers that already. No contradiction.

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

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

The description is compact and front-loaded, opening with the primary action. It uses four sentences, each serving a purpose: purpose, when to use, storage/scope details, and companion tools. It is slightly longer than the minimum but contains no fluff, earning a 4.

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 key-value write tool with no output schema, the description is remarkably complete. It covers what to store, when to use it, persistence behavior, session-specific TTL, scoping by identifier, and how it relates to recall/forget. An agent has sufficient context to invoke the tool correctly without 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?

Input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description adds some usage examples (e.g., 'resolved ticker, target address, user preference') that help illustrate appropriate key/value content, but it does not materially expand on the schema-provided semantics. Therefore, the score remains at the baseline.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with a specific verb ('save'), resource ('data'), and scope ('across this conversation or across sessions'). It also distinguishes from siblings by explicitly naming companion tools 'recall' and 'forget' and providing concrete examples (resolved ticker, target address, user preference).

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and explains the benefit ('so you don't have to look it up again'). It also mentions alternatives by pairing with 'recall to retrieve later, forget to delete.' However, it lacks an explicit when-not-to-use statement, so it falls just short of a 5.

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

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

Annotations already provide rich safety signals (read-only, idempotent, non-destructive), so the description only needs to add behavioral nuances. It discloses that the list covers all repositories indexed by Repology and enumerates the returned fields, which adds context beyond annotations, though it omits pagination or limit details.

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 sentence that places the main verb and object first, then fills in the result details. There is no redundant phrasing or unnecessary caveats.

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 parameters, rich annotations, and an output schema present, the description sufficiently explains the tool's scope and returned information. It would be slightly more complete if it mentioned that the list can be large or noted sorting/pagination, but these are not essential given the output schema.

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

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

The input schema has zero parameters and 100% coverage, so the description has no parameter semantics to add. The baseline for a parameterless tool is 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 uses a specific action verb ('List') and a clearly defined resource ('all package repositories indexed by Repology') plus the key result fields (names, family, package counts). This clearly distinguishes it from any sibling tool that deals with entities or alerts, as no other sibling lists repositories.

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 does not explicitly state when to use this tool over alternatives or mention exclusions. However, the 'List all...' phrasing strongly implies the use case of retrieving the global repository catalog, and no sibling appears to offer a similar repository-listing function.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds significant behavioral context: internal cascading through multiple endpoints, graceful degradation of LEI/FIGI enrichment, explicit labeling of identifier sources, and clear handling of unresolved identifiers. There is no contradiction with annotations.

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

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

The description is lengthy but well-structured: it front-loads with example queries and a clear usage directive, then organizes detail by entity type. Every sentence adds value—the length is justified by the complexity of cross-source resolution. However, it could be slightly trimmed (e.g., the LEI explanation is detailed but somewhat redundant with the 'company' sub-bullet).

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

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

Despite having no output schema, the description implicitly covers return format (identifiers labeled by source, unresolved list). It explains edge cases (ISIN input, graceful degradation, non-US coverage). The tool has moderate complexity (2 params, no nesting) and the description fully addresses how it works, what it returns, and when to use it. 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%, but the description goes well beyond by explaining what each 'type' value resolves to (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand). For 'value', it lists acceptable input formats (ticker, CIK, ISIN, name for company; brand/generic name for drug) and provides concrete examples. This adds semantic richness that the schema alone lacks.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers required by other tools. It provides specific examples like 'What's the ticker for...' and explicitly says 'Use FIRST whenever you have a name but need an ID.' This creates strong differentiation from sibling tools that likely consume IDs rather than names.

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 directs when to use the tool ('Use FIRST whenever you have a name but need an ID'), lists example user queries, and outlines supported entity types (company, drug). It also explains fallback behavior when enrichment services are unavailable, which helps agents understand success/failure modes. The statement 'replaces 2-3 manual lookups' sets clear expectations for efficiency.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already declare the safety profile. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density, which goes beyond the annotations. 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?

Three sentences, front-loaded with purpose, method, and output. Every sentence adds value: what it does, how it works, and when to use it. No filler or repetition of schema fields.

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

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

With no output schema, the description explicitly states the return format (ranked list with score, confidence, signal density per entity), which is valuable. It also explains the internal probe mechanism and use case. Slightly lacks details on edge cases (e.g., empty results), but is otherwise 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 baseline is 3. The description reinforces 'your brand + N competitors' and 'first entry as subject' (also in schema), but does not add parameter syntax or format details beyond what the schema already provides. It neither improves nor degrades the baseline.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and identifies most/least recognized. It uses a specific verb ('Compare') and resource ('AI visibility'), and explicitly mentions the underlying ai_visibility_check probe, distinguishing it from generic comparison 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 a concrete use case ('competitive AI-marketing audits') with an example query, making the intended scenario clear. However, it does not explicitly mention alternatives or when not to use this tool, so it lacks the 'when-not-to-use' guidance typical of higher scores.

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 behavior. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. No contradiction with annotations.

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

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

The description is long but every sentence earns its place: purpose, use cases, ecosystem scope, failure modes, and return fields. It is front-loaded with the core function and avoids 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 and absence of an output schema, the description fully covers return summary fields, per-advisory details, links, alternative versions, ecosystem constraints, and failure behavior. It leaves no significant gaps.

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

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

The input schema already documents both parameters with 100% coverage. The description mentions package and version but does not add semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: a composite npm package check across deps.dev and bundlephobia. The verb 'scan' plus specific resources distinguishes it from 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 usage triggers are given ('whenever an agent asks is X safe / popular / small') and an exclusion is stated ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). This clearly guides when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds non-redundant behavioral details: the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, the 200K character cap with truncation flagging, and the guarantee that passages carry offsets for verification. This exceeds what annotations provide.

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

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

Three tightly packed sentences, front-loaded with the core action. Each sentence adds essential context (what it does, when to use, how it works, limitations) without redundancy or fluff.

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

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

Given the tool's complexity (3 parameters, no output schema), the description fully covers return values (passages with offsets and scores), limitations (200K truncation), and mechanism (embeddings and windows). It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, but the description enhances parameter understanding by giving concrete examples for 'text' (SEC 10-K body, article, long tool result) and 'query' (quoted natural-language query), and implies the meaning of 'limit' via 'top-N passages.' This goes beyond the baseline 3 for high 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 a specific verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings like ask_pipeworx_grounded by explaining it is for searching within already-fetched text, while grounding is for fetching and grounding over relevant passages.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and contrasts with ask_pipeworx_grounded by showing the pairing pattern. This gives clear when-to-use and an alternative, satisfying the dimension fully.

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 contradicts the annotations. It states 'Returns the new subscription id' and describes a create operation, implying each call yields a new subscription. However, idempotentHint=true in the annotations indicates the operation is idempotent. This direct contradiction warrants a score of 1, despite the description's useful behavioral details about authentication and delivery constraints.

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: purpose, return value, prerequisites, supported types with examples, and delivery options with limitations. It is front-loaded with the primary function and efficiently packed, with no extraneous content.

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

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

The description covers core behaviors well but omits the webhook delivery channel (present in the schema) and the patent_grant and clinical_trial types from its 'Supported types' list. Given the complexity of the tool, these gaps leave important context unexplained. However, the schema and annotations fill some gaps, so a 3 is appropriate.

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

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

The input schema already provides detailed descriptions and examples for each parameter, and the description enriches it further with concrete use cases (e.g., 'items:["5.02"] = officer change'), delivery channel specifics (SMS verification, 10/day cap), and webhook semantics. This adds significant meaning beyond the structured schema, so a 5 is justified.

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 indicates it returns a subscription id. This distinguishes it from siblings like list_subscriptions and unsubscribe, making the 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 contextual guidance on when this tool is appropriate: it requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels. It does not explicitly name alternatives or exclusions, but the context makes the use case clear, so a 4 is appropriate.

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

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

Annotations already cover read-only, open-world, and idempotent safety. The description adds valuable behavioral context: output includes category-bucketed examples with exact tool/argument shape, is drawn from a live catalog, and supports optional topic filtering. No contradictions found.

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

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

The description is long but well-structured, front-loaded with sample queries and containing no filler. It efficiently packs purpose, output structure, usage modes, and priority guidance. Slightly longer than strictly necessary but every clause earns its place.

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

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

Since there is no output schema, the description adequately explains return contents (category-bucketed example questions with exact tool+argument shape), invocation variations, and when to use. This fully covers the agent's needs for a simple one-parameter onboarding tool.

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

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

Input schema already has 100% coverage, describing the optional topic parameter with all valid values and the omit-for-full-spread behavior. Tool description repeats these examples (finance, pharma, betting) without adding new semantic detail, so baseline 3 is appropriate.

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

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

Description clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions, each with the exact tool + argument shape. It distinguishes from siblings by explicitly saying to use this FIRST when unsure what Pipeworx can do, and by naming 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?

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools' and explains no-args vs. topic-filtered invocation. However, it does not explicitly state when not to use it or name alternative tools as 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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds that ownership is enforced, the row is deactivated (not deleted), and historical events remain accessible via recent_alerts. This aligns with annotations and enriches the behavioral model.

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

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

Three sentences, front-loaded with the main action. Each sentence adds distinct value: ownership constraint, deactivation behavior, and linkage to recent_alerts. No redundant wording.

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

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

For a single-parameter tool with no output schema, the description is complete: it covers the action, the ownership restriction, the non-destructive nature, and the downstream effect on historical data. Annotations cover idempotency and safety, so nothing critical is missing.

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

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

Schema description coverage is 100% ('Subscription id (uuid) returned by subscribe'), so the schema already fully documents the parameter. The description adds no new meaning about the 'id' beyond stating 'by id,' so baseline 3 is appropriate.

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

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

The description uses specific verb+resource: 'Cancel a subscription by id.' It clearly distinguishes from siblings like 'subscribe' (create) and 'list_subscriptions' (view), and the ownership note adds further specificity.

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

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

The description provides clear context for when to use it (cancel a subscription you own) and mentions that historical events remain available via 'recent_alerts,' implying an alternative. It doesn't explicitly name 'subscribe' or 'list_subscriptions' as alternatives, but the context is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses critical failure semantics: could_not_verify means the check did not happen and must not be treated as evidence, while unsupported means no source covers it. It also reveals the two execution paths and the citation behavior, adding significant context beyond the annotations.

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

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

The description is longer than average but every sentence earns its place: trigger phrases are front-loaded, routing logic is explained, verdicts are enumerated, and the failure caveat is prominently flagged. The claim that it replaces 4–6 sequential calls is a useful efficiency signal, not fluff.

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

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

For a tool with no output schema, the description provides a full picture: verdict vocabulary, the error field for non-execution, the unsupported meaning, routing behavior, and a concrete efficiency justification. An agent has enough information to select and invoke the tool correctly across both financial and non-financial claims.

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 both parameters at 100%, but the description adds practical semantics: tolerance_pct overrides the claim's implied tolerance, recommends 1–2% for hallucination detection, and notes the default is capped at 5%. The claim examples also clarify expected input format, going 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 natural-language trigger phrases and explicitly states the tool performs 'natural-language claim verification against authoritative sources.' It clearly distinguishes from research/compare siblings by focusing on fact-checking with verdicts, not open-ended 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?

It gives explicit when-to-use guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and differentiates the financial-claim structured path from other claims falling through to the grounded pipeline. It does not name specific sibling alternatives or exclusion cases, but the usage context is clear.

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