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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes beyond by disclosing the routing mechanism (picks from 5,529 tools), fills arguments, returns structured answers with stable citation URIs, and works on every tier. Also mentions it's fast, adding operational context not present in annotations.

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

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

The description is longer than ideal but every section earns its place: usage triggers, alternatives, examples, and capabilities. It's front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and structured in a readable flow. A minor trim would make it a 5, but it's already efficient for the complexity it covers.

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 (routing across thousands of sources), the description is complete: it states what it does, when to use it, how it differs from alternatives, example queries, and what the return format looks like (structured answer with citation URIs). No output schema exists, but the description covers the essential outcome sufficiently.

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

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

Schema description coverage is 100%, with all six parameters clearly documented as aliases for the natural-language question. The description does not add extra parameter-level detail, but the schema already fully compensates, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('routes', 'returns') and clearly names the resource (5,529 tools across 1,455 sources). It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and deep_research, and by positioning itself as the default entry point. The examples further clarify intended use cases.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives and their specific purposes. Also lists trigger phrases and example queries, making the decision boundary 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?

Annotations already declare read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is a beta that may change behavior when a candidate is under test, currently matches ask_pipeworx exactly, and 'falls back to nothing'—confirming it is a fully working router. 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 three sentences with no wasted words. Each sentence adds essential information: identity, current status and usage, and the no-fallback guarantee. The specific tool count and date add relevance, though the description is slightly 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?

For a beta variant of a Q&A router, the description covers purpose, current behavior, and usage context thoroughly. It relies on knowledge of ask_pipeworx for the response shape, but that sibling tool is accessible, and the schema provides enough context for invocation. Given the lack of an output schema, this is sufficiently complete.

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

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

The schema covers 100% of parameters with aliases documented. The description only references 'same arguments' without adding new semantics beyond the schema, 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 this is the beta version of ask_pipeworx, identical in tools, arguments, and response shape, but with candidate routing improvements. It distinguishes from the stable ask_pipeworx and ask_pipeworx_grounded by emphasizing its experimental 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?

Explicitly instructs to use it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router to decide merges. This provides a clear selection criterion and context for choosing this over alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behaviors: it performs routing and tool calls, extracts verbatim evidence, returns refusals with specific reasons, and incurs an extra LLM call. This adds substantial context not present in annotations.

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

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

The description is dense but well-structured: purpose first, then return behavior, usage guidance, and cost. Each sentence contributes distinct value with no filler or redundancy.

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

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

Despite no output schema, the description fully explains return values, refusal reasons, and use cases. It integrates sibling context ('Same routing as ask_pipeworx') and cost implications, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (6 parameters, all aliases for 'question'), so the baseline is 3. The description does not add extra parameter meaning beyond what the schema already states; it focuses on behavior rather than input format, which is acceptable given the simple parameter set.

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 hallucination-resistant answer mode for high-stakes reads, with a specific verb ('answer') and resource scope. It distinguishes itself from the sibling ask_pipeworx by emphasizing extraction only from tool results and explicit refusal behavior.

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

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

It explicitly states when to use ('whenever an answer will be quoted, cited, or acted on'), when not to use (casual lookups prefer ask_pipeworx), and names the alternative tool. It also explains the cost trade-off of one extra LLM call.

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

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

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds abundant context beyond those hints: account requirements, paid tier for thorough, parallel execution across 5,529 tools, the findings packet structure, gaps[] and contradictions[] behavior, semantic excerpting (not head-truncation), citation fetchability guarantees, and latency expectations. There is no contradiction with the annotations; the description richly complements them.

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

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

The description is long but every sentence carries essential information for correct invocation: prerequisites, alternatives, output structure, depth behaviors, timing, and limitations. It is front-loaded with the most critical caveats (account required, if not signed in use ask_pipeworx). Despite its length, there is no fluff 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?

Despite having no output schema, the description fully explains the return format: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers edge cases (not signed in, current news topics yielding empty gaps), account/tier requirements, and latency. Given the tool's complexity and the absence of an output schema, this description is exceptionally complete.

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

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

Input schema coverage is 100% with detailed descriptions for both 'question' and 'depth'. The description adds value by providing concrete example questions ('compare X and Y's regulatory + financial exposure') and elaborating on the behavioral implications of depth choices (e.g., 'depth:"standard" re-angles unanswered gaps', 'thorough... chases the best leads', and latency expectations). This goes slightly beyond the schema's own text, though the schema already does heavy lifting.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and clearly distinguishes itself from open-web search and sibling ask_pipeworx. It explicitly notes what makes it unique ('Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL') and provides example use cases. This fully differentiates it from siblings.

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

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

The description is exemplary in usage guidance. It explicitly states when to use the tool ('Best for broad/multi-part questions over structured data'), when not to use it (breaking/current news), and which alternative to use instead ('use ask_pipeworx instead'). It even covers account/tier prerequisites and depth selection (standard vs thorough) with behavioral consequences. This exceeds the bar for explicit when/when-not/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, 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?

Even with annotations declaring read-only and idempotent behavior, the description adds substantial transparency: it lists the exact fan-out sources (SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF), return fields, limits (up to 5 filings), and a known failure mode ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). This goes well beyond annotation basics.

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

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

The description is a single dense paragraph but efficiently packs examples, usage rules, return structure, and caveats into a compact space. It is not broken into sections, but every sentence contributes value; the length 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?

Given the tool's complexity (multiple sources, fallback behavior, no output schema), the description is remarkably complete. It enumerates all return components (CIK, filings with URIs, fundamentals with specific financial metrics, patents, news mentions, LEI), prescribes input format, and clarifies unsupported names. No significant gaps remain for an agent to invoke it correctly.

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

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

The schema already provides 100% coverage with detailed descriptions for both parameters (type enum and value ticker/CIK, including the name-not-supported note). The description repeats these examples but adds no new semantic information, so it does not exceed the baseline for high schema coverage.

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

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

The description clearly states the tool's core function: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific verbs ('profile', 'brief me on', 'research') and distinguishes itself from sibling tools like compare_entities and resolve_entity by focusing on a single entity with a holistic multi-source approach.

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

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

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear exclusion: names are not supported, instructing to 'use resolve_entity first if you only have a name.' This directly addresses when to use the tool and when to use 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 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe read operation. The description goes far beyond this by disclosing response structure (leg-by-leg prices, spread fields), the compatibility_warning logic with two distinct cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. This is comprehensive behavioral disclosure that helps the agent interpret results and edge cases correctly.

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

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

The description is verbose but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS, temporal_alignment, skipped_cross_type). Every sentence contributes essential information about a complex tool. It could be tightened slightly—e.g., the final warning about pre-mapped topics is somewhat redundant after the earlier compatibility_warning explanation—but overall it is organized and front-loaded with the core 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 complexity and the absence of an output schema, the description carries the full burden of explaining return values and caveats. It covers the response format, the safety fields and their triggering conditions, the temporal alignment check, and the skip counters. This is a complete picture for an agent to invoke the tool and interpret its results, including potential false signals.

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

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

The schema already covers all 3 parameters with descriptions, earning a baseline of 3. The description adds meaningful context beyond the schema: it explains what the topic shortcuts represent (e.g., 'fed' auto-fetches the matching event on each venue) and how explicit kalshi_event_ticker and polymarket_event_slug override the topic mapping. This enrichment justifies a score above baseline, though the schema already does the heavy lifting.

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

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

The description opens with a precise definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly states the tool's function and the unique resource pair it operates on, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges. It also details the two operating modes, leaving no ambiguity about what the tool does.

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

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

The description provides clear usage context by explaining both modes (topic shortcuts vs explicit pairings) and when each is appropriate. It includes a strong when-not-to-trust warning: 'pre-mapped ≠ tradeable' and explains the conditions under which spreads are meaningless. However, it does not explicitly name alternative tools or state exclusions like 'use polymarket_arbitrage for same-venue comparisons,' so it falls short of full alternative guidance.

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

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

Annotations already declare 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 annotations, the description discloses non-obvious behaviors: unresolved identifiers are explicitly listed under `unresolved`, GLEIF/OpenFIGI failures degrade gracefully while EDGAR identifiers still return, and each call cascades through multiple lookup endpoints. These are valuable operational traits that set proper expectations.

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

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

The description is dense but well-structured: it starts with usage examples, proceeds to purpose, then breaks down supported types, and finishes with degradation behavior. It is somewhat long but every sentence adds essential context for a multi-source entity resolution tool.

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

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

With no output schema, the description compensates by explaining what identifiers are returned for each type, the `unresolved` field, and graceful degradation. It even includes a citation format for drugs. It stops short of describing the full response envelope but is largely complete for an agent to invoke 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?

Schema already provides 100% parameter descriptions, but the description adds richer meaning by elaborating the `type` and `value` semantics: for company it details the cross-source identity spine (CIK, ticker, LEI, FIGI) and for drug it lists RxCUI, ingredient, and brand, plus gives concrete examples (AAPL, ozempic). This goes beyond the terse schema text.

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

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

The description opens with concrete query examples and clearly defines the tool as resolving a user-spoken name to canonical/official identifiers required by other tools. It further details supported types (company, drug) with specific identifier sources, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', giving a clear and actionable usage trigger. While it doesn't explicitly state when-not-to-use or name alternatives, the priority hint provides strong selection guidance.

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

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

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.