Gunbroker

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds beyond annotations: explains it probes LLMs, scores visibility, returns per-model results, and requires an API key for Anthropic. No contradictions.

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

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

The description is three sentences, front-loaded with the main purpose. Every sentence adds information: first sentence states core function, second covers defaults and key requirement, third describes output and use cases.

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 models, scoring, optional parameters), the description covers key aspects: purpose, default, API key, return structure, and use cases. It does not detail every possible output field, but the described structure is sufficient.

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

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

Schema description coverage is 100%. The description adds value by explaining the default model, which models are supported, and how 'context' aids disambiguation. It also clarifies that '_apiKey' is passed directly to Anthropic.

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 probes LLMs for brand/product visibility and scores them 0-100. It specifies the verb 'probe', resource 'LLMs', and distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by targeting general AI visibility audits.

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

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

The description explains when to use the tool (AI-marketing audits, brand checks, competitive monitoring) and provides specifics on default model and API key requirements. It does not explicitly list alternatives, but the context is 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, openWorldHint, idempotentHint, destructiveHint. Description adds the routing behavior to 4770 tools, argument filling, and citation URIs, which is valuable context 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?

Somewhat lengthy but every sentence serves a purpose: preference guidance, usage examples, alternative recommendations. Structured with 'START HERE' and 'Step up only when needed' for clarity. Could be slightly trimmed but effective.

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

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

Covers purpose, usage, and output (structured answer with citations). Given complexity and no output schema, it provides sufficient context for selection. Lacks details on rate limits or cost, but overall complete.

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

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

Schema description coverage is 100% with all parameters documented. Description mentions aliases but adds little extra parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states it routes questions to a vast set of tools for authoritative structured data with citations. Provides numerous examples and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives when to use (factual questions) and when to use alternatives (hallucination-resistant or broad questions). Includes specific examples and notes breaking news handling.

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

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

Adds significant context beyond annotations: costs one extra LLM call, extracts only from tool result, lists refusal reasons. Annotations already declare readOnlyHint=true, openWorldHint=true, etc., are not contradicted.

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

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

Six sentences, each serving a distinct purpose: definition, process, return format, usage guidance, cost comparison. No fluff, front-loaded with key 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?

Given no output schema, description fully explains return structure and refusal reasons. Covers routing, extraction guarantee, and use cases. Leaves no critical gaps for a high-stakes 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% with aliases documented. Description adds that the question is used for routing and argument filling, but schema already conveys the natural language nature. No gaps, but also no substantial extra meaning.

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

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

The description clearly states it's a 'hallucination-resistant answer mode for high-stakes reads' with explicit verb+resource ('answer mode', 'extracts answer'). It distinguishes from sibling ask_pipeworx by contrasting grounded vs casual lookups.

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 tells when to use: 'whenever an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups'. Provides examples (financial, legal, medical) and explains cost tradeoff.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description greatly expands on these with fan-out examples, response shapes, resolver contracts, parent event extraction, news fallback, safety blocking, and resolution-rule risk, covering all behavioral traits beyond structured fields.

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

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

The description is front-loaded with core purpose and input. Despite length, it uses section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) for structure. Some details like classifier lists and fan-out examples are extensive but necessary for a complex tool; slight verbosity prevents a 5.

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

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

For a tool with 3 parameters and no output schema, the description covers all aspects: input formats, behavioral edge cases, output shapes, blocking conditions, resolution logic, and safety measures. It is exceptionally complete for its 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% with all parameters described. The description adds significant meaning: market parameter explains three input types, depth defines 'quick' vs 'thorough' with evidence count, include_raw details default behavior and use cases for true. This far exceeds schema-only information.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and specifies input types (slug, URL, question text). It differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data gathering and evidence packet generation.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Blocking conditions (low-confidence matches, closed markets, wide spreads) are detailed, but alternatives among siblings are not directly compared, limiting 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 already declare readOnly, openWorld, idempotent, and non-destructive. Description adds valuable behavioral context: off-calendar fiscal year handling, sorting by primary metric, and replacement of 8-15 lookups.

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 with trigger phrases and examples. It is front-loaded with purpose but slightly long. No wasted words, but could be more structured.

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

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

Despite no output schema, description explains return format (paired data + citation URIs). It covers all necessary aspects: entity types, data sources, limits, and sorting. Complete for 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 has 100% coverage with descriptions. Description adds meaning beyond schema: explains what data each type pulls (company: financials from SEC; drug: FAERS counts) and gives examples with values limits.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It lists explicit trigger phrases like 'Compare X and Y' and distinguishes from siblings by preferring over sequential lookups.

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

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

It explicitly says when to use (comparing entities) and prefers over sequential lookups. It provides examples for each type. While it lacks explicit when-not, the context of siblings like entity_profile implies single-entity use.

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

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

Annotations already indicate readOnly, idempotent, openWorld. The description adds context: 15-60s response time, decomposes questions into facets, returns gaps[] for unanswered parts, doesn't invent answers, and works only on structured catalog. This all goes beyond what annotations provide.

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

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

The description is long but well-structured, front-loading key prerequisites (account sign-in). Every sentence adds value, though some details could be condensed. It uses clear separations and examples.

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 explains the return value (findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, gaps[]). It also covers prerequisites, behavior, limitations, and alternatives. Extremely 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?

Schema coverage is 100%, baseline 3. The description adds meaning: 'depth' explained with facet counts per level, 'question' described as natural language and suitable for broad/multi-part. This reinforces and clarifies 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 that the tool performs grounded multi-source research across structured data, returning a findings packet. It distinguishes from sibling tools like ask_pipeworx by specifying it is for broad/multi-part questions and not for breaking news or single lookups.

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

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

Explicitly provides when to use (broad/multi-part questions over structured data) and when not to use (breaking news, single lookups, if not signed in). Names alternatives: ask_pipeworx for single lookups and breaking news. Also mentions account and paid tier requirements.

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. The description adds valuable behavioral context: it returns curated examples, full schemas for each result, and indicates that results are ready to call directly without a second schema lookup. This adds significant transparency 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 structured with purpose first, then use cases, then output description, and finally usage advice. It is slightly lengthy but every sentence adds value. Could be more concise, but overall well-organized.

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 complexity (6 parameters, many sibling tools and no output schema), the description covers purpose, usage context, output details, and ordering advice. It does not explain return format in depth, but mentions enough (top-N with schemas). It is complete enough for effective 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 description coverage is 100% (all 6 parameters described). The description mentions 'query' and provides usage examples, but the schema already handles parameter semantics adequately. The description adds marginal value beyond the schema, hence a baseline 3.

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

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

The description explicitly states the tool finds tools by describing a data or task, listing many specific use cases (SEC filings, financials, FDA drugs, etc.) and clearly describes the output (top-N tools with names, descriptions, full schemas). It distinguishes itself from siblings by advising to call it FIRST when many tools are available, showing a clear and specific purpose.

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

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

The description provides clear guidance on when to use ('Use when you need to browse, search, look up, or discover what tools exist for') and recommends calling it FIRST when wanting to see the option set. However, it does not explicitly state when not to use it or name alternative sibling tools, so it lacks exclusion guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description details the parallel fan-out across multiple sources, soft-failure of patents API after May 2025, and GDELT→GNews fallback for news. This adds significant behavioral context that annotations alone do not capture.

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?

Despite length, every sentence earns its place. The description front-loads example queries, then systematically details outputs and constraints. No fluff; all information is actionable and necessary for correct tool use.

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 fully enumerates return fields (cik, filings with URIs, fundamentals sorted, patents soft-fail, news fallback, LEI). It also covers input constraints and failure modes, making the tool's behavior comprehensive and predictable for an agent.

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

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

The description adds crucial meaning beyond the schema: it clarifies that 'value' can be a ticker or zero-padded CIK, and explicitly states names are not supported (requiring resolve_entity). This prevents common input errors, leveraging the schema's fields but extending their practical use.

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 provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific outputs (cik, filings, fundamentals, patents, news, LEI) and gives example queries, making the purpose immediately clear. It also distinguishes from chaining multiple single-pack lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity if only a name is available, providing clear when-to-use and 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 already provide destructiveHint=true and idempotentHint=true, indicating the tool's destructive and idempotent nature. The description adds context about data types (stale, sensitive) but does not substantially extend 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?

Two concise sentences: the first states the action, the second provides usage guidelines. No wasted words, front-loaded with key information.

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

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

For a single-parameter tool with no output schema, the description covers purpose and usage context adequately. Minor gaps like return behavior or error handling are not critical given simplicity.

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 parameter description 'Memory key to delete.' The description does not add extra semantics beyond the schema, so 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 starts with 'Delete a previously stored memory by key,' clearly stating the action (delete) and resource (memory by key). It distinguishes itself from sibling tools 'remember' and 'recall' by implying different operations.

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 mentions when to use: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with 'remember' and 'recall,' providing context. It lacks explicit exclusions but is clear enough for a simple tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds specifics: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Four sentences, front-loaded with core action, followed by process, output, and use cases. No unnecessary 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?

With no output schema, description compensates by specifying output format. All inputs covered. Lacks mention of error handling or URL restrictions, but adequate for a straightforward 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% with good descriptions. Description restates purpose but adds no new semantic details beyond defaults (max_links default 25, max 50), which is already in 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?

Description clearly states the action (generate llms.txt), the resource (any URL), and the target (AI crawlers). It distinguishes from sibling tools, as none are similar.

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?

Description provides three explicit use cases (client indexing, personal drafting, competitor auditing) but does not offer exclusion criteria or alternatives among siblings, though siblings are unrelated.

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 aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It adds value by specifying that the operation is public and needs only the API key, but does not detail rate limits or response format, which is acceptable given the annotations already cover safety.

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: first sentence states purpose and output fields, second sentence explains authentication. Every word is necessary, no fluff, and the key information is front-loaded.

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 lists all major return fields (title, description, prices, seller, etc.), compensating well. Authentication requirements are clearly stated. For a simple read tool with two parameters, the description is complete and informative.

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 both parameters (itemID and _apiKey). The description does not add further parameter-level details beyond what the schema provides, meeting the baseline expectation.

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

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

The description clearly states the verb (Get), resource (single GunBroker listing), and scope (full details by item ID). It explicitly lists the fields returned, and the distinct purpose from sibling tools like gunbroker_search_items and gunbroker_seller_orders is evident.

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 indicates the tool is public and requires only an API key, giving clear usage context. However, it does not explicitly state when not to use it or mention alternative tools for related tasks, though the sibling list provides implicit context.

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 behavioral context: returns specific fields (item IDs, prices, bid counts, time left), supports pagination and sort, and is for active listings. No contradictions.

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

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

Four sentences with clear, front-loaded action and examples. Every sentence provides essential information without fluff, making it highly efficient and scannable.

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

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

Without an output schema, the description explicitly lists return fields (item IDs, titles, prices, bid counts, time left). It covers purpose, parameters, behavior (pagination, sort), and access requirements. Complete for a search 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% with descriptions for all parameters. The description adds value by giving keyword examples, noting _apiKey is the only credential needed, and implicitly covering pagination and sort parameters. It does not repeat schema but enhances understanding.

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 active listings by keyword, provides relevant examples, and lists return fields. It distinguishes from siblings like gunbroker_get_item (which gets a single item) and gunbroker_seller_orders (seller orders), making its purpose unambiguous.

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

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

The description implies usage for keyword-based search and mentions it's public with only an API key, but does not explicitly state when not to use it or compare with alternatives like gunbroker_get_item. Sibling names provide context, but the description could be more direct.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that the tool returns specific order-related fields and mentions the authentication token exchange, but no additional behavioral traits (e.g., rate limits, data freshness) are disclosed.

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, front-loaded with the action and resource, and contains no redundant information. Every sentence 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?

Given the tool has no output schema and 6 parameters, the description covers the purpose, returned fields, and authentication requirements. It is complete enough for a list endpoint, though a mention of pagination (PageIndex/PageSize behavior) would be helpful.

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 explains the authentication parameters and mentions TimeFrame as optional, but does not add significant meaning beyond the schema descriptions. The context about the token exchange adds some value.

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

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

The description clearly states the tool lists sold orders for the authenticated seller and specifies the returned fields (order IDs, buyers, item titles, totals, payment/shipping status). This distinguishes it from sibling tools like gunbroker_search_items and gunbroker_get_item.

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

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

The description explains the required credentials (developer key, username, password) and the authentication flow. However, it does not explicitly state when to use this tool versus alternatives, leaving some ambiguity for an AI agent.

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

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

Annotations (readOnlyHint, idempotentHint) already declare safe, idempotent behavior. Description adds return field details and the include_inactive parameter, providing additional useful 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?

Two sentences with no waste. First sentence states purpose and output fields; second gives usage guidance. Front-loaded and efficiently 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, and return data completely. No missing information for an agent.

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

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

Parameter include_inactive is fully described in the schema (100% coverage). The description does not add extra meaning about the parameter beyond the schema, so 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 states the tool lists the caller's active subscriptions and enumerates return fields (id, type, params, timestamps, count). It distinguishes from sibling tools subscribe and unsubscribe.

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

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

Provides explicit guidance: use to review monitoring before adding more or to find an id to cancel. Lacks explicit alternatives or when-not-to-use, but context with siblings implies usage boundaries.

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

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

Annotations already indicate non-readOnly, non-destructive, etc. The description adds specific behavioral details: rate-limited to 5 per identifier per day, free, and does not count against quota. This goes beyond annotations, though annotations already cover the basic 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 concise and front-loaded with the main purpose. Every sentence adds necessary information (categories, guidelines, constraints). 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?

For a feedback submission tool with no output schema, the description covers input requirements thoroughly. It explains all parameters and their use. The only missing aspect is a brief note on what the agent can expect as a response, but given the tool's simplicity, it's nearly complete.

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

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

Schema coverage is 100%, so the schema defines parameters well. The description adds value by explaining enum meanings (e.g., 'bug = something broke'), giving examples for message length (1-2 sentences, 2000 chars), and clarifying the optional context object's purpose. This compensates for any ambiguity.

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: sending feedback about broken, missing, or needed functionality. It lists specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on feedback.

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

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

Provides explicit guidance on when to use the tool (bug, feature/data_gap, praise) and what to include/avoid (describe in terms of tools/packs, not end-user prompts). Also mentions rate limits and quota-free nature, helping the agent decide when to invoke.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: the data is self-aggregating from CF analytics-engine, contains no PII, and is cached (5min-1h depending on window). This goes well beyond the annotations and provides clear expectations about data freshness and privacy.

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 extremely concise: three sentences covering purpose, use cases, and behavioral context. Every sentence adds value; there is no fluff. It is front-loaded with the core function ('What other AI agents are calling on Pipeworx right now').

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

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

For a simple tool with one optional parameter, no output schema, and robust annotations, the description is complete. It explains what is returned (top tools, packs, call volume), how it works (self-aggregating, cached, no PII), and when to use it (three use cases). No gaps are apparent.

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 single parameter 'window' is 100% covered by the schema with enum values and a basic description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the schema, justifying a score above the baseline of 3.

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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('returns') and a resource ('top tools, top packs, call volume'). The three explicit use cases further clarify purpose and distinguish it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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 concrete use cases (discovering hot data sources, confirming popular canonical tools, checking alignment with agent needs) that guide when to use the tool. However, it does not explicitly state when not to use it or directly name alternatives, missing a small degree of guidance completeness.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: algorithm (monotonicity checks, partition checks), semantic anchor (Jaccard threshold), partition filter (placeholder slugs), fill check (live CLOB depth), and response structure. No contradictions.

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

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

Well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but slightly verbose. Every sentence adds value, but could be tightened without losing clarity.

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, but description explains response fields (opportunities[], partition_check structure). Covers edge cases (skipped_low_similarity, placeholder fraction filter) and references sibling tool for further actions. Fully complete for 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?

Schema has 2 parameters with 100% coverage. Description adds beyond schema: for 'event', explains slug format and that it walks child markets; for 'topic', explains seed question and cross-event scanning. Provides concrete examples.

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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between event and topic modes, differentiating 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?

Explicitly tells when to call with no args for trending scan, when to use 'event' (specific market) vs 'topic' (cross-event), and recommends 'event' for specific markets. Also advises when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing.

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

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

The description goes far beyond annotations, detailing caching (1h KV-level), response structure with sections and diagnostics, and model family logic. It adds critical behavioral context like 'Your edge may already be in the price' and filtering conditions, fully complementing the readOnlyHint and idempotentHint 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 comprehensive but verbose, with extended detail on model families and diagnostics. While structured well (top-level sections noted), it could be more concise by trimming redundant technical descriptions without losing clarity.

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 thoroughly covers response structure, all knobs, diagnostics, and caching. It explains why segments might be empty and provides filter rationale, making it highly complete 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?

With 100% schema coverage, the description adds meaningful context beyond default values and usage examples (e.g., 'Edge is evaluated NET of slippage' for min_edge_pp). It explains when to adjust knobs like slippage_pp and min_liquidity, enhancing parameter understanding.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market prices, with a specific audience in mind ('what should I bet on today'). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on data disagreement edges rather than pure arbitrage.

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 strong usage context ('Built for what should I bet on today') and details tradeable-edge knobs for filtering. However, it does not explicitly compare with siblings or state when not to use this tool, leaving some ambiguity.

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?

Description adds significant context beyond annotations: snapshot reading behavior, trend computation, decay calculation using absolute edge_pp_net, and explanation of expired opportunities. Annotations already declare read-only, idempotent, and non-destructive; description reinforces and enriches this with concrete data handling details.

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

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

Description is detailed but front-loaded with the core question and response structure. It could be slightly more compact, but each sentence contributes useful information. The RESPONSE section is well-organized with bullet-like descriptions.

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

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

Despite lacking output schema, description fully explains all parts of the response (tracked, expired, snapshot_dates) and covers edge cases (snapshot gaps, TTL limits). Parameters and limitations are also well handled. No missing needed context.

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

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

Schema covers both parameters with descriptions; description adds default values, clamp range (2-30 for days), and clarifies window values meaning. This goes beyond the schema's information, making parameter usage very clear.

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

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

Description clearly states tool's purpose: edge persistence and decay telemetry using daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from related tools like polymarket_edges by focusing on time-series analysis rather than raw edges.

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?

Tool implicitly teaches when to use it by contrasting fresh wide edges vs old wide edges. It notes limitations like history depth bounded by 60-day TTL and snapshot gaps. Could be more explicit about when not to use, but context from sibling tools helps.

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?

No contradiction with annotations (readOnlyHint, idempotentHint, etc.). The description adds behavioral context: it 'walks the ladder', returns verdicts (clean, degraded, cannot_fill), and warns about forced directional risk. For baskets, it details per-leg fill behavior and thin_legs detection.

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, using sections for single-market and basket modes, and bolding key requirements. Every sentence adds value, though it is slightly verbose. However, given the tool's complexity, this level of detail is justified.

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

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

The description completely explains return values for both modes, listing all fields and their meanings. It also covers edge cases (thin legs, forced directional risk) and provides the verdict criteria. No output schema exists, so the description carries full burden and meets it thoroughly.

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 parameter descriptions. The description adds significant context: explains default side logic for baskets ('auto — sell if partition sum > 1, buy if < 1'), clarifies size_usd meaning for singles (spend/target proceeds) vs baskets (settlement notional), and provides constraints (clamp 10–1,000,000).

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

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

The description clearly specifies the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and explicitly relates to sibling tools like polymarket_arbitrage and polymarket_edges, stating usage in context of their signals.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overrun may not be capturable, partial fills create directional risk) and covers required parameters for each mode.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds valuable behavioral context: it explains safety fields like compatibility_warning, temporal_alignment, and counters for dropped comparisons. It honestly admits that most pre-mapped topics return warnings, setting 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 longer but well-structured with clear sections: purpose, two modes, response fields, and safety warnings. Every sentence adds value, though slight trimming could improve conciseness. It appropriately front-loads the key 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?

Despite no output schema, the description thoroughly explains the response structure: leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and counters. It covers all relevant context for understanding the tool's output and limitations, making it complete for a read-only data 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%, with each parameter described in schema. The description adds meaning beyond schema: it explains the two modes, provides exact values for topic, gives examples for explicit parameters, and clarifies override logic. This enriches parameter understanding for correct invocation.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by specifying the cross-venue scope. The verb 'spread' and resource 'cross-venue' are specific.

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 explains two modes (topic shortcuts and explicit pairings) with precise when-to-use guidance. It warns when compatibility_warning fires, explaining when spreads are not meaningful due to non-equivalent bet shapes or temporal misalignment. This provides clear context for appropriate invocation.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining scoping ('Scoped to your identifier') and pairing with remember/forget, going 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 extremely concise with two sentences, no wasted words, and front-loaded with the core action. Every sentence 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?

The tool has low complexity (one optional param, no output schema). The description fully covers its purpose, usage pattern, and relationship to siblings, making it complete.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reinforces and adds the nuance that omitting the key lists all keys, which complements the schema.

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

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

The description clearly states the action ('Retrieve a value previously saved via remember, or list all saved keys') and the resource (saved memories). It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and includes scoping details. It lacks explicit when-not-to-use instructions but provides clear context.

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 destructiveHint=false. The description adds behavioral details: returns source, citation_uri, raw payload; explains mark_read flagging behavior; and confirms polling is safe. 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 somewhat lengthy but front-loaded and well-organized. Each sentence contributes: purpose, returned data, filters, mark_read behavior, polling and alternative. Could be tightened slightly, but it is efficient and clear.

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

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

Tool has 5 optional parameters with no output schema. Description covers the key return fields (source, citation_uri, raw payload) and the mark_read side effect. Does not detail limit or unread_only beyond schema, but given moderate complexity and high schema coverage, it is adequately complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The description adds context for type (example 'sec_8k'), since (ISO timestamp), and mark_read effect, but this is supplementary. With full schema coverage, the baseline is 3, and the description meets that without significantly exceeding.

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 'Pull fired events from your subscription feed' and lists the returned data (source, citation_uri, raw event payload). It differentiates from sibling tools by mentioning the alternative REST endpoint for scripts/dashboards, making the tool's specific role 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?

Provides guidance on filtering by type and since, and the mark_read parameter. Mentions that polling works fine and directs users to the same feed via GET registry.pipeworx.io/alerts.json for scripts/dashboards, offering an alternative. Lacks explicit when-not-to-use but gives sufficient context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable context about parallel fan-out, source fallback logic, and soft-fail for USPTO. 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 informative with multiple sentences, but every sentence adds value. It is front-loaded with example queries. Slightly verbose 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?

No output schema, but description details return structure (changes[] grouped by source, total_changes, citation URIs). It covers sources and their status. Could mention error handling or empty results, but overall complete for the tool's 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 has 100% parameter description coverage. The description adds examples (ISO date format, relative shorthand), clarifies the 'type' enum only supports 'company', and recommends typical values for 'since' (e.g., '30d' or '1m'). This exceeds schema alone.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, fanning out to multiple sources. It distinguishes itself from the sibling tool 'entity_profile' by specifying when to use the static profile instead.

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 tells when to use (e.g., 'what's new' queries) and when not to use (use entity_profile for static profile). Provides default values for the 'since' parameter and explains fallback behavior between GDELT and GNews.

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

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

Adds value beyond annotations: explains scoping by identifier, persistent vs ephemeral memory, and that it stores key-value pairs. No contradiction with annotations (idempotentHint=true is consistent with key-value overwrite).

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?

Concise 4-sentence description, front-loaded with overall purpose, then usage context, behavioral details, and sibling references. 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?

For a simple tool with 2 params and no output schema, the description covers purpose, usage, behavior, and ties to siblings comprehensively.

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 has 100% coverage with descriptions for key and value. The description adds example values but does not significantly extend parameter meaning beyond schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool saves data for later reuse, with specific examples like 'resolved ticker, target address, user preference'. It clearly distinguishes from sibling tools recall 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?

Describes when to use: 'when you discover something worth carrying forward'. Explicitly mentions pairing with recall and forget, and differentiates persistence based on authentication.

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 significant context: internal cascading through multiple endpoints, auto-disambiguation for companies, and specific return fields including citation URIs. 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 one well-structured paragraph, front-loaded with examples and purpose. Every sentence adds value; no wasted words. Efficient and clear.

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

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

No output schema exists, so the description fully explains return values for both entity types (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). Covers all necessary details for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: for company, value can be ticker, CIK, or name; for drug, brand or generic. Also mentions auto-disambiguation, which adds value beyond 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 uses specific verbs (resolve, look up) and resources (ticker, CIK, RxCUI) and distinguishes from sibling tools by stating it replaces 2-3 manual lookups. It clearly states the primary use case: converting a user-spoken name to a canonical identifier.

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 FIRST whenever you have a name but need an ID.' Provides example queries and supported types. Does not explicitly list when not to use it, but the guidance is strong and context is 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds transparency by explaining the internal process: probes each entity with ai_visibility_check, ranks results, and surfaces scores. It also mentions API key requirements for certain models.

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 (~70 words) and front-loaded with the core purpose. Every sentence adds value, with no redundancy.

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

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

Given the tool's complexity (4 parameters, no output schema), the description fully explains the return format (ranked list with score, confidence, signal density) and the internal process. It covers the behavioral context beyond annotations.

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 baseline is 3. The description adds meaning by clarifying that the first entity in 'entities' is the subject and rest are competitors, and explains the role of optional parameters like models and context.

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 that the tool compares AI visibility across multiple entities side-by-side, ranking them by score. It differentiates from sibling tools like ai_visibility_check and compare_entities by specifying the competitive audit use case and the multi-entity comparison.

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 specifies when to use (competitive AI-marketing audits) and hints at usage by mentioning that the first entity is treated as the subject. It implies the tool is for comparing a brand against competitors, but does not explicitly state when not to use or alternatives.

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

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

Annotations already indicate read-only, idempotent, safe. Description adds critical details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timed-out sources. 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?

Well-structured: purpose first, then use cases, then limitations and edge cases. Every sentence provides value, no fluff.

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

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

Fully describes inputs, behavior (fan-out, partial failures, timing), return content (summary, advisories, links, alternatives), ecosystem scope, and fallback options. No output schema, but description compensates fully.

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 clear descriptions for both parameters. Description adds minor value: scoped packages accepted, version defaults to latest. Since schema already does the heavy lifting, score is above baseline.

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

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

Description clearly states the composite check for npm packages, fans out to deps.dev and bundlephobia, and lists specific data points. No sibling tools overlap with this function.

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

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

Explicitly says when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also explains NPM-only in v1 and directs to deps.dev:version for other ecosystems.

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, etc. The description adds vital details beyond annotations: embedding model (BGE-base-en), chunking (overlapping 500-char windows), similarity (cosine), character limit (200K with truncation flagging), and that passages include offsets for verification. No contradictions.

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

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

Two concise sentences plus a technical note. Front-loaded with core action ('Semantic search INSIDE a fetched record'), then usage context, then implementation details. Every sentence serves a purpose; no 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?

No output schema exists, but the description explains return format (top-N passages with offsets and scores). It covers edge cases (truncation, flagging) and pairs with a sibling. Given the tool's complexity, this is fully complete.

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

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

Schema coverage is 100%. The description enriches each parameter: for 'text' it gives concrete examples (SEC 10-K, article), for 'query' it provides domain-specific examples, for 'limit' it states default and range. Adds meaning beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by framing the use case: when a record is too large for the prompt, contrasting with ask_pipeworx_grounded which uses grounding over entire documents.

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: 'Use when the record is too big to cram into the prompt — search_within saves context.' Also provides workflow guidance by pairing with ask_pipeworx_grounded, making it easy to decide between tools.

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

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

Annotations already indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds valuable context: requires OAuth, returns subscription id, details delivery channels with limits (10/day sms), webhook signing secret returned once. 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 well-structured, starting with the main purpose, then requirements, then type details, then delivery options. It is somewhat lengthy but every sentence adds value. Could be slightly more concise, but the structure is logical.

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

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

Given the complexity (3 params, nested objects, no output schema), the description is fairly complete. It explains return value (subscription id) and mentions webhook secret. The openWorldHint suggests possible unspecified side effects, but overall coverage is good.

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 significant meaning by providing concrete examples for each type (e.g., sec_8k items, polymarket_edge topic) and explaining delivery sub-parameters in detail, far beyond the schema's brief 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 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The title 'Subscribe to Alerts' reinforces purpose.

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

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

The description explains when to use this tool (creating subscriptions) and includes requirements (Pipeworx OAuth account). However, it does not explicitly contrast with alternatives like list_subscriptions or recent_alerts, which would provide clearer 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 read-only, idempotent, and non-destructive. The description adds valuable context: it returns category-bucketed example questions drawn from a live catalog and includes the exact tool+argument shapes. 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 front-loaded with common user queries, then explains output and usage. Every sentence earns its place, though it could be slightly more compact without losing clarity.

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 one optional parameter and no output schema, the description fully covers purpose, usage, parameters, and output format. It includes example usage and notes that results are live, making it complete for a simple discovery 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% with a single optional parameter. The description adds meaning by listing valid focus areas ('finance, pharma, etc.') and explaining behavior when omitted, which goes beyond the schema's 'Optional focus area' label.

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 returns example questions categorized by topic, with exact tool/argument shapes serving as an onboarding entry point. It distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by its specific output and 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?

Explicitly says 'Use this FIRST' and explains when to call with no argument vs with a topic. It does not explicitly list when not to use, but the guidance is clear enough to avoid misuse against alternatives like 'ask_pipeworx'.

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 indicate a non-read-only, idempotent, non-destructive operation. The description adds value by disclosing ownership enforcement and the deactivation (not deletion) behavior, which goes beyond the annotations. However, it could be more explicit about error handling (e.g., invalid id).

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 action, and no unnecessary words. Every sentence adds value: the first defines the action, the second explains constraints and side effects.

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 simple context (one parameter, no output schema, no nested objects), the description adequately covers the tool's purpose and behavior. It mentions ownership, deactivation, and linkage to recent_alerts. It could briefly note the return format on success, but overall it is complete enough for an AI agent to use 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 input schema has 100% coverage for the single parameter 'id', with a clear description linking it to subscribe. The tool description merely restates 'by id' and does not add new semantic information beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the action 'Cancel a subscription by id', specifying the resource (subscription) and the identifier. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by describing the cancellation 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?

The description provides clear context: it is for canceling your own subscriptions, with ownership enforcement. It explains the effect (deactivation, not deletion) and mentions recent_alerts for history. However, it does not explicitly state when not to use it or list alternatives beyond the implied contrast with subscribe.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by explaining the data sources (SEC EDGAR + XBRL), the types of verdicts returned, and the inclusion of citations, which goes 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 well-structured, starting with trigger phrases, then usage guidance, and then capabilities. It is somewhat lengthy but each sentence adds value. No redundancy, slightly more concise would improve but still effective.

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

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

Given the single parameter with full schema coverage, clear annotations, and the description covering verdict types and data sources, the definition is complete for the tool's purpose. The description fills the gap of missing output schema by explaining return values.

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 description coverage, the baseline is 3. The description provides example claims but does not add significant new meaning beyond the schema's description of a natural-language factual claim.

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

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

The description clearly identifies the tool's purpose: verifying natural-language claims against authoritative sources, specifically for company-financial claims. It provides multiple trigger phrases and distinguishes it from sibling tools by focusing on structured financial data verification.

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: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain of company-financial claims. However, it does not explicitly mention when not to use or compare to alternatives beyond noting efficiency gains.

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