Figshare

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds valuable context beyond annotations, such as the free default model, 'BYO key' cost implication for Anthropic, and the return structure. It does not contradict the annotations.

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

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

The description is four sentences long, front-loaded with the primary purpose, followed by default behavior, return format, and use cases. Every sentence contributes information 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?

For a tool with no output schema, the description explains the per-model result structure and combined view, plus default behavior and use cases. It could include more detail on how scoring works or what 'signals' means, but the information provided is sufficient for correct use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the default model ('Workers AI Llama-3.3-70b'), when to pass `_apiKey`, and how the `context` parameter helps disambiguate. This goes 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 purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is specific and includes the resource and expected output. However, it does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence' or 'compare_entities', so it falls short of a 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?

The description provides explicit use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default model selection and optional Anthropic probing. However, it does not mention when not to use this tool or name alternatives, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful context about versioning and the specific fields returned, which 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?

Two sentences, front-loaded with the primary action and resource. No redundant wording, every phrase adds value.

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

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

With an output schema present and rich annotations covering safety, the description provides all necessary context: purpose, parameter roles, and a summary of return fields. It is complete for a read-only fetch 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%, so the description must explain parameters. It does so by identifying 'id' as a numeric identifier and 'version' as an optional specific version. This adds meaningful semantics beyond the raw schema, though it lacks constraints like range or default behavior.

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 fetches full metadata for a single Figshare article by numeric id, optionally at a specific version. This specific verb-resource pair distinguishes it from siblings like 'articles' (likely list) and 'article_files' (likely file list).

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 use for fetching a single article's metadata, contrasting with list tools, but does not explicitly name alternatives or state when not to use. The context is clear enough for an agent to decide, but lacks explicit exclusions.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable context about the return payload (file names, sizes, MIME types, direct download URLs) and the optional version parameter, going beyond what annotations provide. 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 a single, front-loaded sentence that directly states the action, resource, and return values. No filler or redundant information; every element 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 with two parameters and an output schema. The description covers purpose, key input, and return fields, which is sufficient for a straightforward list operation. It omits edge-case behaviors like empty results or pagination, but the annotations and output schema mitigate the need for further 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 description coverage is 0%, so the description must compensate. It clarifies 'id' as numeric and mentions 'version' as optional, but does not elaborate on version semantics (e.g., version of the article) or provide additional parameter details beyond the schema examples. Basic compensation, not comprehensive.

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: listing downloadable files attached to a specific Figshare article, identified by numeric id, with an optional version. It specifies the action, resource, and scope, and implicitly distinguishes from sibling tools like 'article' and 'articles' by focusing on files.

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

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

The description implies usage context (retrieving article attachments) and identifies the key input (numeric id) and optional version. However, it does not explicitly compare with alternative tools or provide exclusions, so it falls short of full guidance but is still clear.

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

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

Annotations already declare read-only and idempotent behavior, so the description's main additions are repository scope and return metadata. It discloses that it returns DOI, authors, license, download URL, but doesn't cover pagination or sorting behavior beyond what schema provides. This adds some context without contradicting annotations.

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

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

The description is four sentences, each providing distinct value: scope, preference guidance, return type, and example use cases. It is front-loaded with the primary purpose and uses emphasis for key guidance. Slightly longer than minimal but not verbose.

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

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

With an output schema present and annotations covering safety, the description fills the main remaining gap of when to prefer this over alternatives. It could add detail on pagination or parameter interactions, but overall it's sufficient for effective selection. The examples and scope information make it contextually rich.

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 40% (order and item_type have descriptions), but the tool description does not clarify query, page, page_size semantics. The use cases imply query usage but don't explain parameter formatting or constraints. Given low schema coverage, the description fails to compensate adequately.

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 search across figshare for academic research outputs, listing content types and return fields. It distinguishes from web search and PubMed/arXiv, demonstrating a specific verb+resource scope. While it doesn't explicitly contrast with sibling 'article', the search vs. detail distinction is clear.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' for specific use cases like finding datasets and supplementary materials, and provides concrete examples ('find datasets about X'). It also notes PubMed/arXiv limitations, giving clear when-to-use guidance. It doesn't mention sibling tools, but alternative positioning is strong.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals non-obvious behavior: it automatically routes to one of 5,767 tools, fills arguments, and returns stable pipeworx:// citation URIs. It also transparently directs users to a more grounded sibling when verbatim evidence and confidence are required, giving a realistic picture of its behavior.

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

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

The description is long but front-loaded with the most important directive (prefer over web search) and dense with useful routing detail. The domain list and examples earn their place, though some repetition of 'factual question' concepts could be tightened without much loss.

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

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

For a tool with one required parameter and no output schema, the description covers what to send, what the tool does internally, and what kind of response to expect (structured answer with citations). Minor operational details like latency, rate limits, or failure behavior are absent, but they are not essential for correct selection and invocation.

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

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

The schema already fully documents the single required question parameter and its aliases. The description adds practical semantics by clarifying what kinds of natural-language questions are appropriate, with concrete examples and trigger phrases, which helps an agent formulate the parameter correctly.

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

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

The description clearly identifies this as a question-routing tool that answers factual/current-data questions across many authoritative sources, returning structured answers with citations. It distinguishes itself from web search and names relevant siblings like deep_research and ask_pipeworx_grounded, making the tool's role unmistakable.

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

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

It explicitly says to prefer this tool over web search for factual, current, or historical data questions, and gives concrete trigger phrases and examples. It also provides routing guidance: use ask_pipeworx_grounded for grounded/evidence-tight answers and deep_research for broad multi-part questions, plus notes that breaking news is already handled via news-feeds packs.

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 meaningful behavioral context: no candidate is currently active, it currently matches ask_pipeworx exactly, candidate improvements are enabled live when under test, and it falls back to nothing because it is a full working router. This gives the agent an accurate model of experimental behavior without contradicting the readOnly/idempotent hints.

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

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

The description is a bit longer than strictly necessary, but every sentence carries distinct value: identity, current candidate state, usage guidance, and no-fallback clarification. It is front-loaded with the core purpose and remains readable.

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

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

For a simple router taking a natural language question, the description is complete: it explains the current behavior, the relationship to the stable router, when to use it, and what to expect in terms of response shape. With rich annotations and full schema coverage, there are no critical 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 description coverage is 100%, so the baseline is 3. The description only repeats that arguments are identical to ask_pipeworx and does not add parameter-level meaning beyond what the schema already provides. This is acceptable but not additive.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx: an identical universal router with the same 5,767 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by framing it as the experimental edge with candidate routing improvements.

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

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

It explicitly states when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router to decide what merges, which gives the agent a clear selection heuristic relative to the sibling.

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

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

Goes far beyond the annotations by detailing the exact output structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and enumerating possible refusal reasons. It also discloses the extra LLM call cost and the strict extraction-only-from-result behavior. 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 dense and front-loaded with the core concept. Every sentence carries distinct information (mode, routing, extraction guarantee, output shape, refusal reasons, use cases, cost tradeoff). It is slightly long but appropriate given the complexity and absent output schema.

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

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

Despite having no output schema, the description completely specifies the return/refusal formats and enumerates all error categories. It additionally provides decision-relevant context by comparing cost with the sibling tool, making the overall usage context fully actionable.

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

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

The schema already provides 100% coverage for all six parameters, which are simply aliases for a single question string. The description adds no additional meaning about the parameters themselves; it only contextualizes when to use the tool, which is already captured under usage guidelines.

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

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

The description states a specific verb and resource: it answers questions via Pipeworx using a grounded, hallucination-resistant mode. It distinguishes itself from the sibling ask_pipeworx by emphasizing that it extracts answers ONLY from the tool result, which is a clear differentiator.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and directly names the alternative with a preference condition: 'prefer ask_pipeworx for casual lookups.' This leaves no ambiguity about when to choose this tool.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals critical behaviors: low-confidence matches 'short-circuit with status:"low_confidence_match" and suppress analysis fields', closed/dead markets return 'status:"market_closed_or_inactive" and skip fan-out', and it warns about cancellation-rule risk ('audited arb-bot ledgers show flat-50¢ void settlements are a recurring pure-rules loss'). 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 well-structured with clearly labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RISK RISK). It is front-loaded with purpose and usage, but it is verbose and could be trimmed without losing core value.

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

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

No output schema exists, but the description compensates with detailed response shapes: 'result.market carries best_bid/best_ask/spread_pp/liquidity/price_change_1h/1d/1w', 'result.analysis carries model_probability/edge_pp/kelly_fraction_half', and explains resolver contract and edge cases like news fallback fields. It covers safety, closed markets, wide spreads, and cancellation rules – highly complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The description reinforces the market parameter with examples but adds no extra semantics for depth or include_raw beyond the schema; the fan-out examples are contextual but not parameter-level details.

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

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

The description opens with 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' – a specific verb (research), resource (Polymarket bet), and method (pulling Pipeworx data). It also distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on single-bet research with evidence pack, and provides classifiers and fan-out examples.

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

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

The description explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' – clear when-to-use guidance. It doesn't explicitly name alternative tools to exclude, but the context of the tool's scope is clear and it explains the resolver contract to ensure the agent knows when to trust the output.

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 safe read-only, idempotent, and non-destructive behavior. The description adds the 'parent → leaves' hierarchy detail, providing useful context about the output structure beyond the annotations. It does not mention pagination or ordering, but for a simple list tool this is acceptable.

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

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

The description is a single, front-loaded sentence that directly states the action and resource. There is no verbosity or redundant information, making it highly concise and well-structured.

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

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

Given the tool's simplicity (no parameters), the presence of an output schema, and comprehensive annotations, the description is complete. It provides the key detail about hierarchy and does not need to explain return values or usage conditions beyond what is already structured.

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?

With zero parameters, the description does not need to explain parameter meanings. The baseline for no-parameter tools is 4, and the description is clear enough for the agent to invoke it correctly without parameter details.

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

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

The description uses a specific verb ('List') and identifies the resource ('Figshare categories'), and it even clarifies the hierarchical structure ('parent → leaves'). This distinguishes it from generic listing tools and aligns with the tool's name and title.

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

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

The description implies usage for fetching the category hierarchy but does not explicitly state when to use it versus alternatives. There is no mention of when not to use it or comparison with sibling tools, so the guidance is only implied.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds the specific return fields (title, description, authors, DOI, article ids) which is useful, but this content is likely covered by the output schema. It does not disclose additional behavioral aspects like authentication, rate limits, or error handling.

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, well-structured sentence that front-loads the action and resource, and includes specific examples of the metadata returned. No words are wasted, and the description is immediately understandable.

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

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

For a simple read operation with one parameter, an output schema, and strong annotations, the description is sufficiently complete. It provides the essential information an agent needs to select and invoke the tool, and 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?

With 0% schema description coverage, the description compensates by stating 'numeric id' and 'Figshare collection', giving meaningful context to the single 'id' parameter. It does not provide further format details or examples beyond the schema's type and example, but it adequately clarifies the parameter's purpose.

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 ('Fetch full metadata'), the resource ('a single Figshare collection'), and the identifier format ('numeric id'). It also lists what is included in the metadata, distinguishing it from sibling tools like 'collections' which likely list multiple collections.

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 'single Figshare collection by numeric id' gives clear context for when to use it (when one specific collection's metadata is needed), and the sibling name 'collections' implies the alternative for listing. However, it does not explicitly mention alternatives or exclusion criteria, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful behavior: supports pagination and specifies return fields. No contradictions exist.

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 concise sentences front-load the main action and add pagination and return info. No wasted words.

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

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

The tool has strong annotations, an output schema, and simple params. The description covers core purpose and pagination, but does not explain behavior when no query is provided (since all params are optional). Overall adequate.

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%, so the description must compensate. It does assign meaning to query ('keyword query') and page/page_size ('pagination'), but lacks detail on types, defaults, or constraints.

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

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

The description clearly states the tool searches Figshare collections by keyword, using a specific verb and resource. It does not explicitly distinguish from the sibling 'collection' tool, which likely fetches a single collection.

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

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

The description implies usage for keyword searches across collections, but it does not explicitly state when to use this tool over alternatives like 'collection' or provide exclusions. Usage context is present but not fully articulated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond these by disclosing data sources (SEC EDGAR/XBRL, FAERS, FDA), off-calendar fiscal year handling, automatic sorting, and output of paired data with citation URIs per entity. 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?

At approximately 120 words, the description is reasonably compact and front-loaded with the most critical information. Each sentence adds distinct value: intent triggers, preference rule, type-specific behavior, sorting, and output format. It is slightly dense but well-structured without redundancy.

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

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

Despite lacking an output schema, the description conveys the return shape ('paired data + pipeworx:// citation URIs per entity') and sorted results. It also covers fiscal-year handling for companies, which is a subtle but important detail. Minor gaps like error handling or unit formatting are acceptable given annotations and the simple parameter set.

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

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

Schema already covers both parameters with descriptions and examples, so coverage is 100%. The description adds meaningful detail by explaining what each type retrieves: company pulls 10-K financial metrics, drug pulls FAERS counts and FDA/trial data. It also reinforces that 'values' expects tickers/CIKs vs drug names.

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 user-intent phrase patterns ('Compare X and Y', 'X vs Y', etc.) and states exactly what the tool does: side-by-side comparison of 2–5 companies or drugs in one parallel call. It clearly distinguishes itself from sequential single-pack lookups and uses specific verbs like 'pulls', 'returns', and 'sorted' to define its scope.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states it 'Replaces 8–15 sequential lookups'. It provides actionable context for when to use company vs drug types and what to expect from each, making the selection criteria unambiguous.

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

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

Annotations already signal read-only, open-world, and idempotent behavior, and the description adds substantial context beyond that: parallel decomposition across 5,767 tools, explicit gaps[] arrays with never-invented findings, resolvable citation_uri values, semantic excerpting, contradictions[] for standard/thorough, latency expectations, and the paid-plan constraint for thorough. 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 and front-loaded with the account requirement and main purpose, and nearly every sentence adds operational value. However, it is a single long paragraph with some repetition of the ask_pipeworx alternative, so it could be better structured with separation between purpose, alternatives, behavior, and latency.

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

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

Even though there is no output schema, the description fully explains the return envelope: findings with verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop fields, and fetchable citation URIs. It also covers authentication, pricing, timing, and alternative routing, leaving no critical gap for an agent deciding whether 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 coverage is 100%, so the baseline is 3. The description adds meaningful depth semantics beyond the schema: it clarifies that thorough is paid, that standard and thorough include a contradictions scan, and that thorough adds an iterative lead-chasing hop. This goes beyond the schema's enum descriptions and helps the agent choose the right depth value.

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

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

The description names a specific verb and resource: grounded multi-source research across Pipeworx's 1506 structured data sources in one call. It also explicitly distinguishes itself from open-web search and from ask_pipeworx, which covers single lookups and live news, so an agent can clearly tell this tool apart from its siblings.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it is best for broad/multi-part structured-data questions, while single lookups and breaking/current-news topics should go to ask_pipeworx. It also states the account prerequisite and directs unsigned-in users to ask_pipeworx, and it explains which depth settings to use for richer research.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: it returns top-N results with 'names, descriptions, and full input schemas (with curated examples)', and states results are 'ready to call directly, no second schema lookup needed.' This informs the agent of the output format and immediate usability, which the annotations do not convey.

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

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

The description is concise yet information-dense: two sentences that front-load the core purpose, then cover usage context, return value, and when to call. Every clause earns its place; there is no fluff or repetition. It is well-structured for quick parsing by an agent.

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

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

For a simple discovery tool with a single required parameter and no output schema, the description is complete. It covers what input to provide (describing the data/task), what the output looks like (top-N tools with schemas), and the intended usage context (first call when many tools are available). No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the query parameter and its aliases, plus the limit parameter. The description only implicitly references the query concept ('describing the data or task'), adding no additional semantic detail beyond what the schema provides. Baseline 3 applies since the schema carries the explanatory load.

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 uses a specific verb (find) and resource (tools), and the phrase 'browse, search, look up, or discover what tools exist' removes ambiguity. It distinguishes itself from sibling tools by being the tool-discovery meta-tool, explicitly listing the domains it covers.

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

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

The description gives explicit when-to-use guidance: 'Use when 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).' The qualifier 'not just one answer' implicitly tells the agent not to use this when a single, known tool is appropriate, providing a clear exclusion criterion.

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

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

Despite strong annotations (readOnly, idempotent, openWorld), the description adds substantial behavioral context: the list of source systems, the USPTO sunset soft-fail, the expected-empty FDA section for non-biologic companies, sources_used/sources_failed semantics, and the private-company resolved:false handling. It also declares that type values are interchangeable. This goes well beyond what annotations alone provide.

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

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

The description is long, but it is front-loaded with usage intent and then systematically details sources, return fields, and edge cases. The density is justified by the tool's complexity and the absence of an output schema, though it remains a wall of text with semicolon-separated fields rather than compact scannable 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 multi-source fan-out and no output schema, the description is exceptionally complete: accepted inputs, all output sections, source fallback behavior, empty-data semantics, and failure modes are covered. An agent can predict exactly what will happen for public, private, and data-sparse companies.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful nuance: names resolve via SEC EDGAR company-name match, resolved_from/resolved_to appear when value was a name, and both type values accept the same value shapes. This extra resolution behavior helps an agent construct valid inputs beyond the schema's enum/example 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 names a specific deliverable—'full cross-source profile of a US public company'—with concrete query examples and an explicit preference over chaining single-source lookups. It distinguishes the tool from source-specific siblings by emphasizing the holistic, single-call nature. The resource and scope are unmistakable.

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

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

It explicitly states when to use: whenever the user asks for a holistic view ('tell me about X', 'brief me on...') and says to prefer it over chaining single-pack SEC/XBRL/news lookups. It does not name sibling alternatives such as compare_entities or deep_research, and it does not give a definitive when-not-to-use beyond the implied private-company resolved:false path, so it is not a full 5.

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

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

Annotations already declare destructiveHint true and idempotentHint true, so the safety profile is known. The description adds that it clears 'sensitive data the agent saved earlier,' which is useful, but it does not disclose edge cases like what happens if the key does not exist. 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?

Two sentences with zero wasteful content. The verb and resource are front-loaded, and the second sentence provides practical usage guidance. Every word earns its place.

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

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

This is a simple single-parameter deletion tool. Annotations cover the destructive and idempotent nature, and the description gives when-to-use guidance plus related tools. No output schema is present, but for this operation the description is sufficient 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 the property 'key' described as 'Memory key to delete.' The description only mentions 'by key' without adding further parameter detail, so the schema carries the load; baseline 3 is appropriate.

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

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

The description opens with the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key,' making the tool's function unambiguous. It clearly distinguishes this from sibling tools like remember and recall by focusing on deletion.

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 contexts: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, but does not explicitly state when *not* to use this tool or name alternatives for retrieval, so 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the operational behavior: fetching the page, extracting title/description/key links, and emitting markdown. It also states the output is a single text blob, giving the agent a clear expectation of 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 three sentences long, front-loaded with the main action in the first sentence. Every sentence adds distinct value: purpose, process, and use cases, with no filler.

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

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

Given no output schema, the description compensates by explaining what the returned artifact is ('single text blob ready to drop at site-root/llms.txt'). It also covers the operational flow and common use cases, making it suitably complete for a 2-parameter tool.

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

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

The input schema already covers both parameters with descriptions, including defaults and max for max_links. The description does not add new parameter-level details, so a baseline score of 3 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 uses a specific verb ('Generate') with a clear resource ('production-ready llms.txt file') and scope ('for any URL'). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on the llms.txt generation output.

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

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

The description provides three explicit use cases under 'Useful for:', covering client work, personal projects, and competitive auditing. It does not explicitly name alternative tools, but the context is clear enough for an agent to identify when this tool 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, informing the agent this is a safe read operation. The description adds the output fields (id, name, url), which is useful for understanding the return structure. No contradictions with annotations; the description aligns with a read-only listing.

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, front-loaded with 'List', and contains no superfluous information. Every word contributes to understanding the tool's purpose.

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

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

Given the tool's simplicity, no parameters, and an output schema, the description is entirely sufficient. It covers the purpose and the specific license fields. The annotations cover safety and idempotence, so no additional behavioral disclosure is needed.

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

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

The tool has zero parameters, so the description doesn't need to explain any. Per the baseline for 0 parameters, this scores 4. The description also mentions the fields returned, which provides context for what the output contains.

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 'List Figshare license options (id, name, url)' which clearly identifies the action (list), the resource (Figshare license options), and the output fields. This distinguishes it from sibling tools like categories or collections.

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

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

The description provides clear context: it is for listing Figshare license options. While it doesn't explicitly mention alternatives, the specificity of 'Figshare license options' makes it obvious when to use this tool versus other list tools. There are no exclusions or preconditions needed for such a simple list operation.

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 provide strong safety signals (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the bar for additional transparency is lower. The description adds valuable context: it scopes results to the caller, notes active-only by default, and lists the exact return fields. This enriches behavioral understanding without contradicting annotations.

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

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

Two sentences, each earning its place: the first states the operation and output fields, the second provides usage guidance. No filler, no redundancy, front-loaded with the core action.

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

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

The description fully covers what the tool does, what it returns, and when to use it. The output fields are enumerated, making up for the lack of an output schema. Annotations handle safety, and sibling tools (subscribe/unsubscribe) supply surrounding context. 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?

The schema fully documents the lone parameter (include_inactive) with description and default. The main description's mention of 'active subscriptions' aligns with the parameter but adds no extra semantic depth. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly identifies the operation: 'List the caller's active subscriptions' – a specific verb and resource. It enumerates the returned fields and distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on the review/cancel use case.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly guides the agent to use it before adding subscriptions (subscribe) or when needing to cancel (unsubscribe), referencing the sibling tools without naming them.

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, so the description carries the burden and handles it well. It discloses the claim_token flow (filing without an account returns a token; the token can later retrieve resolution status), the rate limit of 5 per identifier per day, and that it is free and does not count against quota. 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 dense but front-loaded with the core purpose and usage. Every sentence adds functional info except perhaps 'The team reads digests daily and signal directly affects roadmap,' which is motivational rather than invocational. It is slightly longer than necessary but remains well-structured and readable.

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

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

With no output schema, the description compensates by explaining the claim_token return path, rate limits, and server-boundary exclusion. It does not fully specify what happens when filing with an account (e.g., whether a response/status is returned), and the 'identifier' in the rate limit is vague. Still, the coverage is strong for a feedback tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining how to frame the message ('in terms of Pipeworx tools/packs, don't paste the end-user's prompt') and by clarifying the claim_token lifecycle (filing returns it; passing it back later reads the status). This is a meaningful enhancement, though the schema already documents most parameter mechanics.

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 pair ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly lists the feedback categories (bug, feature, data_gap, praise). It also distinguishes this tool from siblings by limiting it to Pipeworx-served tools, so it is unambiguous.

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

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

The description gives explicit when-to-use guidance: wrong/stale data (bug), missing tool (feature/data_gap), or praise. It also gives a clear when-not-to-use exclusion: if the tool came from a different MCP server, file with that server instead. This is exactly the kind of alternative-selection guidance the dimension asks for.

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

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

The description adds meaningful context beyond the annotations: 'derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' These details inform the agent about data freshness, privacy, and output simplicity, which are not covered by readOnlyHint or other 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, front-loaded with the primary purpose in the first sentence, followed by use cases and then implementation details. Every sentence adds distinct value with no redundancy or filler.

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

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

The tool has a single optional parameter and no output schema, so the description carries full burden for return-value explanation. It states the output includes 'top tools, top packs, and total call volume' and narrows it to '(pack, tool, count)', which is sufficient. Caching and window semantics are also disclosed, making the description complete for this simple tool.

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

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

Schema coverage is 100% and the only parameter 'window' is fully described with enum values and a note about shorter vs longer windows. The main description mentions the window options but adds no extra semantic value beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' This is a specific verb+resource combination that distinguishes it from siblings like discover_tools or ask_pipeworx, and the phrase 'right now' clarifies the temporal nature.

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

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

The description provides explicit use cases: 'Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...' It does not explicitly name alternatives or when-not-to-use, but the clear context and purposes make it easy to decide when to invoke this tool.

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

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

Goes far beyond the readOnly/openWorld/idempotent annotations by disclosing concrete behavior: the 3pp threshold for partition checks, Jaccard ≥0.30 similarity filter, placeholder-slug filtering (>20% returns null), and the fill check mechanism that tells users when an edge is not realizable in the book. This is rich, non-obvious behavioral detail.

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

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

The description is long but exceptionally well-structured: it opens with purpose, then details each mode in order, then covers filters, response format, and fill check. Every sentence carries unique information, and key terms are capitalized for scanability. No redundancy or filler.

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

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

With no output schema, the description fully describes the response structure (`opportunities[]` with fields, `partition_check{...}`), explains edge-case behavior (placeholders, low similarity, fill check), and provides practical trade advice ('do not trade it'). This is a model of complete documentation for a complex tool.

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

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

Even though schema coverage is 100%, the description adds substantial semantic meaning: it explains that `event` accepts a slug or full URL, that `topic` is a seed question that triggers cross-event search, and describes the interplay between the two modes. This turns bare parameter names into actionable guidance.

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+mechanism: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between the three invocation modes (no args, event, topic) and explains what each does, setting it apart from sibling tools like polymarket_edges and polymarket_fill_risk.

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 for every mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It even names an alternative for custom sizing (polymarket_fill_risk), giving clear usage boundaries and 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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond this by detailing the model families, response structure (by_segment), edge fields, slippage handling, 24h-move warning, placeholder filtering, caching at KV level, and diagnostics funnel. It also explains internal decision rules such as 'partitions with >20% placeholder fraction skipped entirely'. 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 a clear purpose, but it quickly becomes a very long, single-paragraph wall of text. It includes many implementation details (per-sport alpha values, relaxed gate thresholds, placeholder slug filters) that could be condensed or structured with bullets. While every sentence carries some information, the lack of structure and excessive length make it less concise than it could be.

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 (9 parameters, no output schema), the description is remarkably complete. It outlines the top-level response fields (by_segment, fed_candidates, fed_note, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), filter effects, and caching behavior. An agent has enough context to invoke the tool and interpret the result without needing an 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 description coverage is 100%, so the baseline is 3. The description adds meaningful context for key knobs: it explicitly names 'TRADEABLE-EDGE KNOBS' and explains that min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable', and clarifies min_partition_leg_kelly's special per-leg behavior. This adds value 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 purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is specific about the resource (Polymarket markets) and action (scan and return opportunities), and the phrase 'what should I bet on today' adds a concise use case. It also distinguishes from sibling tools like polymarket_arbitrage by emphasizing Pipeworx data disagreement and the three response segments.

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

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

The description gives clear context for when to use this tool: for 'what should I bet on today' discovery without paging hundreds of markets, and it explains internal filtering (Fed bets, placeholders). However, it does not explicitly say when NOT to use it or mention alternative sibling tools (e.g., polymarket_arbitrage) for different cases, so it falls short of full 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 mark it as read-only/idempotent/non-destructive, and the description adds substantial behavioral context: snapshots written on cache-miss, gaps meaning no scan, 60-day TTL history bound, and decay based on daily closes rather than intraday. 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 information-dense; every sentence earns its place. It uses clear structural labels (Args, RESPONSE, LIMITS) and is front-loaded with purpose, making it easy to scan.

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

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

With no output schema, the description fully specifies the response shape (tracked[], expired[], snapshot_dates[]) and explains edge cases like missing snapshots and TTL limitations. It is complete for a read-only telemetry tool with two parameters.

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

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

Schema coverage is 100% and each parameter already has a full description with defaults and options. The description's Args section paraphrases the same information without adding new meaning, so it provides no boost 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling polymarket_edges by focusing on historical persistence rather than live edge scanning.

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 sets clear context by explaining that this tool is for evaluating edge decay, including an illustrative contrast between fresh and week-old edges. It doesn't explicitly name alternatives or when-not-to-use, but the purpose statement strongly implies when this tool should be selected over siblings.

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

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

Annotations already denote readOnlyHint=true, but the description goes far beyond by explaining the two modes (single-market vs basket), how size_usd is interpreted differently in each mode, return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, capture_ratio, thin_legs, forced_directional_risk), and the exact failure mode of partial fills. No contradiction with annotations; the description adds substantial behavioral context.

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

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

The description is long but structurally efficient: it uses caps to separate modes, colon-separated lists to enumerate return values, and every sentence delivers critical operational detail. There is no filler or redundancy; the density is justified by the tool's complexity.

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

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

With no output schema, the description carries full responsibility for explaining return values, which it does comprehensively. It covers all parameters, both modes, edge cases (thin legs, forced directional risk), and practical risk guidance. The description is fully self-contained for an agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, but the description enriches parameter meaning significantly: it defines market/event as mutually exclusive modes, explains side enums with defaults in both modes, and clarifies that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. This goes well beyond the schema's terse descriptions.

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

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

The description opens with a specific, non-tautological phrase: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly names the resource (Polymarket order books, market/event) and the action (fill-risk edge check), and it distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on realizability and slippage, not just detecting edge.

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 contains explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create unhedged positions), making the when-and-why very clear.

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

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

Despite readOnlyHint, openWorldHint, and idempotentHint annotations already covering safety, the description goes far beyond them. It discloses that unknown metric_type/match_subtype legs are never paired, that compatibility_codes[] can be non-empty even when matches exist, that temporal_alignment null means 'could not be computed' rather than aligned, that Kalshi fees are not modeled so spreads are gross, and exactly what each compatibility code means. This is exemplary behavioral disclosure.

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

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

The description is long, but the tool is genuinely complex with many caveats, and nearly every sentence adds distinct value. It is well-structured with section markers like TWO MODES, RESPONSE, SAFETY FIELDS, and explicitly calls out codes and counters. It could be trimmed slightly, but the density is justified by the need to prevent misuse.

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

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

Given the tool's complexity, the absence of an output schema, and the many edge cases involved, the description covers everything an agent needs: modes, response shape, safety fields, compatibility codes, skipped-leg counters, fee caveats, and the unreliability of pre-mapped topics. No critical behavioral or interpretive gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and their example formats. The description adds meaningful semantics beyond the schema by explaining that explicit parameters override the topic-mapped side and that both modes run the identical token-overlap matcher. This is a clear improvement over baseline, though it does repeat some schema content.

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 computing cross-venue spreads between Kalshi and Polymarket for the same resolving question, with the first sentence stating the core action and scope. It also explains the two operating modes (topic shortcuts and explicit ticker/slug pairing). It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, so it stops just short of a 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?

The description gives explicit guidance on when to use topic mode versus explicit mode: topic mode auto-fetches pre-mapped events, while explicit mode allows custom pairings. It also provides strong when-not-to-use context by warning that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable. It does not name alternatives among sibling tools, so it is not a perfect 5.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds valuable context beyond this: scoping to an identifier (anonymous IP, BYO key hash, or account ID), the list-all behavior when the key is omitted, and the lifecycle pairing with remember/forget. No contradictions with annotations.

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

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

Three sentences, front-loaded with the core action, and every sentence earns its place. The description covers function, use case, scoping, and companion tools without any 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 simplicity, one optional parameter, and good annotations, the description is largely complete. It explains what is returned in list mode, but does not explicitly state return format for single-key retrieval or error behavior; this is inferable but not stated. Still adequate for a memory retrieval tool.

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

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

The schema covers 100% of the single parameter, including the 'omit to list all keys' behavior. The description reiterates this same guidance without adding new syntax, format, or edge-case information. Baseline of 3 is appropriate since schema carries the burden.

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

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

The description uses specific verbs 'Retrieve' and 'list' with a clear resource: values previously saved via remember. It explicitly distinguishes the two modes (by key vs. list all) and differentiates from siblings by naming the companion tools remember and forget.

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: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with remember and forget, which implies alternatives, but does not explicitly state when not to use it or name an alternative lookup tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses a key state-changing behavior: setting mark_read:true flags returned events read, affecting subsequent calls. It also describes the event payload contents, which is important since no output schema is provided.

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 four sentences, front-loaded with the main action, and every sentence adds distinct value: purpose, return content, filtering, mark_read behavior, and an alternative access method. There is no redundancy or wasted words.

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

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

Despite the absence of an output schema, the description sufficiently explains the return shape and the semantics of key parameters. It also covers polling suitability and provides an endpoint for scripts/dashboards, making it complete for reliable tool 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?

With 100% schema coverage, the baseline is 3. The description adds a concrete type example ('sec_8k') and explains the consequence of mark_read:true ('the next call only shows newer ones'), which supplements the schema's descriptions. It also mentions the raw event payload, clarifying the return structure.

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: 'Pull fired events from your subscription feed.' It specifies the returned data (source, citation_uri, raw event payload) and distinguishes itself from subscription management siblings like list_subscriptions by focusing on alert retrieval.

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 by noting 'Polls work fine' and offering an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools like recent_changes, so exclusions are implied rather than stated.

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

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

Even though annotations already declare readOnly/openWorld/idempotent/non-destructive, the description adds meaningful behavioral detail: source fallback (GDELT→GNews), rate-limit handling, USPTO soft-fail due to API sunset, and the returned structure including citation URIs. This goes well beyond the annotations.

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

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

The description is dense but every sentence contributes: query examples, source list, fallback behavior, parameter guidance, return shape, and sibling distinction. It is front-loaded with user-intent examples, making it easy to scan.

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

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

With no output schema, the description fully discloses the return type (structured changes[] grouped by source, total_changes count, pipeworx:// URIs) and edge cases (source fallback, API sunset soft-fail). For a multi-source tool with three parameters, this is complete without being padded.

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, but the description adds practical guidance beyond the schema: it reiterates accepted since formats with examples and recommends '30d' or '1m' for typical monitoring. This extra usage hint justifies a 4.

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

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

The description states a specific purpose: a change feed for a company over a recent window, with example natural-language queries. It explicitly distinguishes itself from entity_profile, which covers static profile data, so the agent can disambiguate between siblings.

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

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

The description states when to use this tool (for 'what's new' / 'latest' style queries) and names the alternative entity_profile for static profile needs regardless of window. It also explains that the tool fans out to multiple sources in one parallel call, implying batch behavior.

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

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

The description adds behavioral context beyond annotations: key-value storage scoped by your identifier, persistent memory for authenticated users, and 24-hour retention for anonymous sessions. This complements the idempotentHint with lifecycle details, though it doesn't describe return values or overwrite semantics.

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

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

Four sentences, each serving a distinct purpose: purpose, usage, storage mechanics, and companion tools. It's front-loaded with the verb and wastes no words.

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

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

For a simple key-value store with full schema coverage and relevant annotations (idempotentHint), the description covers purpose, usage, persistence behavior, and relationships to recall/forget. No output schema exists, so not describing return values is acceptable.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds the key-value scoping context ('scoped by your identifier') but doesn't provide new syntax or format details, so baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Save data the agent will need to reuse later.' It distinguishes itself from sibling tools by positioning as the store operation alongside 'recall to retrieve later, forget to delete,' making its role unambiguous.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, user preference). It also names alternatives (recall, forget), giving clear when-to-use vs. alternative-tool guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses valuable behavior: graceful degradation of LEI/FIGI enrichment, internal cascading lookups, explicit 'unresolved' field, and the figi_candidates mechanism. 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 dense and front-loaded with the core purpose and usage. It is long but every sentence contributes value; minor redundancy in the long list of query examples could be trimmed, but overall structure is clear.

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 compensates by explaining return behaviors, edge cases (unresolved identifiers), and degradation scenarios. It fully prepares an agent to invoke the tool correctly and interpret results.

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

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

Although schema coverage is 100%, the description adds crucial semantic detail: examples for ticker/CIK/ISIN/names, warning against passing full noun phrases, and explanation of ISIN-to-LEI mapping. It significantly enriches the schema definitions.

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

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

The description clearly states the tool's purpose: resolving a user-spoken NAME to canonical/official identifiers. It gives specific verb ('resolve') and resource (identifiers), and lists supported types ('company', 'drug') with details, distinguishing it from siblings like compare_entities and entity_profile.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains behavior when ambiguous ('asserts nothing and returns figi_candidates'), but does not explicitly name alternative tools or conditions when NOT to use, so a small gap remains.

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

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

The description discloses the internal process: 'Probes each entity ... with ai_visibility_check, ranks by score, surfaces which is most/least recognized' and the return format: 'Returns ranked list with score, confidence, signal density per entity.' This adds behavioral context beyond the annotations (readOnly, openWorld, idempotent), such as the delegation to ai_visibility_check and the aggregation behavior.

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

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

The description is three sentences, each earning its place: purpose, mechanics, and use case/output. It is front-loaded with the main action and includes 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 tool with no output schema, the description adequately covers the return values ('ranked list with score, confidence, signal density per entity') and explains the overall comparison narrative. It also gives a realistic example that clarifies the tool's value in competitive analysis, making it complete for an agent to understand when and how to use 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 description coverage is 100%, so all parameters are documented in the schema. The description adds minimal param-specific insight beyond what the schema already provides, such as clarifying the first entity is the subject ('your brand + N competitors'), but this is also in the schema's entities description. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' This is a specific verb+resource+scope, and it distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility and multi-entity ranking.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It implies when to use (comparing multiple entities) but does not explicitly name alternatives or exclusions. This is clear context without explicit when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds behavioral context: composite fan-out, graceful degradation with sources_failed, and latency warning for first bundlephobia measurement (5-30s). 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 lengthy but every sentence contributes useful information—data sources, return fields, ecosystem scope, failure behavior. Well-structured, though not as terse as ideal.

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, so the description's enumeration of return fields (summary block fields, per-advisory detail, links, alternatives) provides necessary context. It also covers edge cases (partial failures, timeouts, ecosystem limitation).

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?

With 100% schema coverage, the baseline is 3; the description adds little beyond stating 'version history' and 'alternative versions' context, but doesn't introduce new parameter semantics not already in the schema.

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

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

The description clearly defines the tool as a composite 'should I add this npm package to my project' check, naming specific data sources (deps.dev, bundlephobia) and result categories. It distinguishes from any sibling by being the only npm-focused scanning tool.

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

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

Explicitly states when to use: whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. Also gives exclusion: non-NPM ecosystems fall under deps.dev:version directly.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds valuable details: it returns passages with character offsets and similarity scores, enables verbatim verification, and discloses the truncation cap at 200K chars. It also explains the embedding model and windowing, which goes beyond annotations.

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

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

The description is dense but each sentence adds value: purpose, use case, pairing, and technical limits. It is front-loaded with the core action and only includes necessary technical details. Slightly long but not wasteful.

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 covers return format (passages with offsets and similarity scores), input constraints (200K char truncation), and usage context. It also mentions the pairing with ask_pipeworx_grounded, making it complete for an AI 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%, so the baseline is 3. The description reinforces the 'text' as already-pulled record and 'query' as natural-language, but adds little beyond the schema's own descriptions. It does mention top-N passages which aligns with limit.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' a specific verb and resource. It clearly distinguishes from siblings by emphasizing 'the text you already pulled' and 'Use when the record is too big to cram into the prompt,' differentiating it from ask_pipeworx and grounded tools.

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

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

It explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names the alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and alternative.

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

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

The description discloses key behavioral aspects: it returns the new subscription id, requires authentication, and details delivery constraints (sms phone verification, 10/day cap). It does not mention the webhook channel or side effects like subsequent alert delivery, but annotations already declare readOnlyHint=false and openWorldHint=true, which cover the write nature and external interactions. No contradictions with annotations.

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

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

The description is a dense but well-organized paragraph that front-loads the primary purpose and then expands into types and delivery channels. Every sentence provides useful information, but it is lengthy. The structure is logical (purpose -> requirements -> types -> delivery), making it scannable despite the length.

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

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

The description omits the 'webhook' delivery channel entirely, even though the schema includes it. This is a gap because it implies only email and sms are optional, potentially misleading an agent. However, the schema compensates by fully documenting webhook behavior. Return value is succinctly stated ('Returns the new subscription id'), and the lack of an output schema is mitigated. Overall, incomplete due to the missing channel overview.

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 description enriches the schema significantly by providing concrete examples for each subscription type (e.g., 'sec_8k' items:["5.02"] = officer change) and clarifying delivery semantics (email, sms, with constraints). It adds meaning beyond the raw schema, even though the schema already has 100% coverage, by explaining real-world usage patterns and caveats.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb ('Create') and resource ('subscription'), and distinguishes itself from sibling tools like list_subscriptions and unsubscribe. The supported types are enumerated, making the 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?

The description provides a clear prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and lists supported types with examples, giving the agent contextual guidance on when to use it. However, it does not explicitly contrast with alternatives (e.g., say 'use this to create, list_subscriptions to view, unsubscribe to remove'), though the verb and sibling names imply this. This is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context beyond these by detailing the return format: 'category-bucketed example questions... each with the exact tool + argument shape.' It also explains the effect of omitting or passing the `topic` parameter. This is useful behavioral disclosure, though it doesn't mention error conditions or rate limits, which are less critical given the annotations.

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

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

The description is somewhat lengthy but well-structured: it opens with a list of natural-language triggers, then explains the output, usage, and priority. Each sentence carries informational weight, though the initial list could be slightly trimmed without loss of usefulness. It earns a 4 for being mostly efficient.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers everything needed: what it returns (categorized examples with tool+argument shape), how to invoke it, and when to use it (first interaction, learning meta-tools). It even mentions the live catalog source. This is complete for an 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?

The schema already describes the `topic` parameter with 100% coverage. The description adds extra semantics by giving concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it yields a 'cross-category spread' while passing it 'focus[es]' the results. This enriches the schema's dry definition.

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: 'the onboarding entry point for an agent that just connected and wants to know what is worth asking.' It specifies the resource (Pipeworx) and verb (returns example questions), and differentiates from siblings like discover_tools by emphasizing it provides 'the exact tool + argument shape' for each question. This is a specific, actionable description.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to use it (no arguments for full spread, or pass `topic`). However, it does not explicitly mention when not to use it or name alternative tools like discover_tools, hence a 4 rather than 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 annotations, the description discloses meaningful behavioral details: the row is deactivated rather than deleted, and historical events remain available via recent_alerts. This explains the nondestructive nature and gives the agent a clear picture of side effects.

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

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

The description is two sentences with no filler. The main action is front-loaded, and each sentence provides essential information: the action, the ownership rule, and the persistence behavior.

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

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

For a simple single-parameter mutation tool, the description covers purpose, ownership, and post-cancellation behavior. With annotations providing safety and idempotency context, the only minor gap is the lack of explicit return-value description, but this is not critical for a cancel operation.

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

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

The input schema fully documents the id parameter (uuid returned by subscribe), so baseline is 3. The description adds value by stating the ownership constraint on that id, clarifying that only subscriptions owned by the caller can be canceled.

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 begins with 'Cancel a subscription by id,' which uses a specific verb and resource, clearly distinguishing it from related tools like subscribe and list_subscriptions. It also adds a concrete scope (subscriptions) and a clear action (cancel).

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

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

It clearly implies when to use the tool (to cancel a subscription) and adds an important prerequisite/ownership rule ('you can only cancel your own subscriptions'). It does not explicitly name alternatives, but the purpose is obvious and no exclusions are missing.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral detail: the verdict set, the critical distinction between 'could_not_verify' (verification_error, not evidence) and 'unsupported' (no source covered), the routing to SEC EDGAR vs. grounded pipeline, and the output shape with citations and reasoning. This goes well beyond the structured annotation safety profile.

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 front-loaded with trigger phrases, then flows logically: purpose, routing, output, caller cautions, and efficiency context. Every sentence adds meaningful information—no filler. Despite its length, it remains well-structured and information-dense.

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

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

The description covers the tool's purpose, routing logic, return values (verdicts, actual value, citation, reasoning), and error semantics. It even warns callers about misinterpreting 'could_not_verify.' With no output schema present, this description fully compensates and gives the agent enough context to invoke the tool correctly and interpret results.

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

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

The input schema already describes both parameters fully (100% coverage), including the tolerance_pct range, default, and override semantics. The tool description adds no extra parameter-level details beyond what the schema provides, so the baseline 3 applies.

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

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

The description opens with concrete trigger phrases and states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes the tool from siblings by noting it replaces 4–6 sequential calls and routes company-financial claims through a structured SEC EDGAR fast path vs. a grounded pipeline for all other factual claims.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing behavior for company-financial vs. other claims and mentions replacing multi-step sequential calls, but it does not explicitly name alternative tools or state when NOT to use this tool. Thus it has clear context but lacks explicit exclusions/alternatives.

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