Rebrickable

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the default model is free, _apiKey is passed directly to Anthropic (not stored), and mentions the return format per model. This aligns with annotations and adds useful context beyond them.

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

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

The description is concise (3 sentences) and front-loaded with the tool's purpose and key capability. Every sentence adds value without unnecessary detail.

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 4 parameters with full schema coverage, safety annotations, and no output schema, the description adequately explains the tool's behavior and return format (per-model score, confidence, signals, raw_response). It is complete for an AI agent to decide when and how to call it.

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

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

All 4 parameters have descriptions in the schema (100% coverage). The description adds context about the default model being free and Anthropic requiring a BYO key, but does not significantly extend what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100) per model. It specifies the default free model and optional Anthropic integration, distinguishing it from sibling tools like 'ask_pipeworx' which answer questions rather than audit visibility.

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 lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to provide an API key ('anthropic' model requires _apiKey). However, it does not explicitly state when NOT to use it or directly compare to sibling tools.

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

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

Annotations mark it as read-only, open-world, and idempotent, which the description does not contradict. It adds meaningful behavior: routing to an internal catalog, filling arguments, and returning 'structured answer with stable pipeworx:// citation URIs.' It also notes performance traits ('works on every tier, one fast call'), which goes beyond the structured fields.

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

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

The description is long but well-structured, front-loading the key directive ('PREFER OVER WEB SEARCH') and using signposts like 'START HERE' and 'Step up only when needed.' While some promotional/redundant phrasing exists, the examples and alternatives justify the length for a default entry-point tool.

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

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

Despite having no output schema, the description tells the agent what to expect ('structured answer with stable pipeworx:// citation URIs') and describes scope ('5,366 tools across 1396 verified sources'). It also covers limitations by naming more specialized siblings, so an agent can decide when this tool is insufficient.

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 'question' field and aliases documented. The description supplements this with concrete examples ('current US unemployment rate', 'Apple's latest 10-K', '5-day forecast for Tokyo') and reiterates that aliases are accepted, making it easy to construct valid inputs.

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

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

The description clearly identifies the tool as a router that answers factual questions via structured data: 'Routes the question to the right one of 5,366 tools across 1396 verified sources... returns the structured answer.' It also distinguishes itself from siblings by name ('ask_pipeworx_grounded', 'deep_research') and from web search.

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

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

It explicitly states when to use it ('Use whenever the user asks...', 'START HERE for most questions') and when to use alternatives ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'). This is clear, actionable 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?

Adds substantial context beyond annotations: explains current state (no active candidate, matches ask_pipeworx exactly), clarifies it is a full working router not a fallback, and describes the experimental edge. No contradiction with readOnly/openWorld/idempotent hints.

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

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

Four sentences, all informative and front-loaded with the beta definition. Slightly longer than strictly necessary, but each sentence earns its place.

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

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

Provides sufficient context for a router tool with no output schema: mentions same response shape, experimental state, and fallback behavior. Could elaborate on what happens when a candidate is active, 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 covers 100% of parameters with descriptions for question and aliases; description adds only 'same arguments' reference, which is redundant and does not deepen parameter understanding 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?

Clearly identifies as a beta version of ask_pipeworx, a universal router with 5,366 tools, and explicitly distinguishes it from the stable ask_pipeworx by noting the experimental candidate routing improvements. Specific verb+resource+scope.

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

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

Explicitly states to use it exactly like ask_pipeworx when wanting the newest routing, and mentions results are compared against the stable router. This provides clear when-to-use and aligns with the alternative 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?

The description adds substantial behavior beyond annotations (readOnly, openWorld, idempotent): it discloses refusal reasons, the extra LLM call cost, evidence extraction from tool results, and the return format for both success and refusal. This provides actionable transparency for an agent.

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

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

The description is dense but every clause earns its place: purpose, mechanism, output format, failure modes, usage guidance, and cost trade-off are all covered without fluff. It is front-loaded with the core purpose and structured for quick scanning.

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 explains the return structure and refusal reasons. It also covers routing behavior, cost, and when to prefer an alternative, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, with all six parameters documented (question plus aliases). The description does not add parameter-specific semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly states a specific verb ('answer mode') and resource, distinguishing it from sibling ask_pipeworx by emphasizing hallucination resistance, evidence extraction, and explicit refusal behavior. It immediately conveys the tool's unique value proposition for high-stakes reads.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This clearly delineates when to use this tool versus the sibling, including the cost trade-off.

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 readOnly, openWorld, idempotent, non-destructive. Description adds detailed behavioral traits: low-confidence resolution suppression, closed market handling, wide-spread market warnings, resolution-rule risk parsing, and parent event extraction. 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?

Well-structured with examples, classifiers, fan-out patterns, response shapes, and edge cases. Every sentence adds value. Front-loaded with main 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 comprehensively details response fields, safety mechanisms, and special cases. Covers all necessary context for effective tool use.

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

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

Schema coverage 100%. Description explains the 'market' parameter accepts slug, URL, or question text; 'depth' values quick/thorough; 'include_raw' behavior. Adds meaning beyond schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). Distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by its comprehensive research scope.

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

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

Explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. Provides classifiers and fan-out examples. Lacks explicit comparison with sibling tools, but usage context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the tool is safe. The description adds that it returns a list with specific fields, which is helpful but not critical 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?

Two sentences, no waste. Front-loads the action and output, then states the use case.

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 parameters and an output schema present, the description is complete. It tells what the tool returns and why to use it, meeting all needs for a simple list tool.

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

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

The tool has no parameters, so the description adds meaning by explaining what the output contains. The schema provides no details, so the description fully compensates.

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 returns a complete list of LEGO colors with specific fields (color id, name, RGB hex, is_trans). It also explains the purpose: to get valid color_id values for filtering parts, distinguishing it from sibling tools like 'parts'.

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

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

The description explicitly says 'Use to get valid color_id values for filtering `parts`,' providing clear context for when to use it. It does not mention when not to use, but the intended use is unambiguous.

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

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

Beyond annotations (readOnlyHint, etc.), description details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles fiscal year nuances, and explains output format (paired data, citation URIs, sorting by primary metric).

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 trigger phrases upfront, 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?

Given complexity (two entity types, multiple data sources, no output schema), description is comprehensive: covers triggers, entity handling, response format, and efficiency benefits.

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. Description adds meaning: explains what each type retrieves, provides example values, and notes constraints (2-5 items, tickers for companies, names for drugs).

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

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

The description uses specific verb 'compare' and clearly identifies resources (companies, drugs) with examples of natural language triggers. It differentiates from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Explicitly states when to use the tool ('ALWAYS PREFER...') and mentions alternatives (sequential single-pack lookups). Provides clear context for comparison scenarios.

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 only indicate read-only/idempotent, but the description adds extensive behavioral context: account restrictions, paid tier for 'thorough', parallel decomposition into facets, findings packet with gaps[] and 'never invented', second-hop iteration, contradictions[], semantic excerpting, and latency expectations. 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?

Despite being long, every sentence delivers critical information: account requirements, usage alternatives, output format, depth nuances, and timing. It is front-loaded with the most actionable info (sign-in required, use ask_pipeworx if not) and then layers technical details logically.

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

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

For a tool with no output schema and high complexity, the description fully covers expected outputs (findings packet, gaps[], contradictions[], hop field, citation_uri), behavior (semantic excerpting, parallel routing), and constraints (account, latency). Nothing essential appears missing.

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

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

Schema coverage is 100%, yet description substantially enriches parameter meaning. It explains depth options in detail (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with leads chasing), and provides example questions for the 'question' parameter. This goes well 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 the tool's function: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources... in ONE call.' It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and breaking news, making the unique value proposition obvious.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx', 'For BREAKING... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Named alternatives and 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, destructiveHint=false, idempotentHint=true. Description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly', which is useful beyond annotations. 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?

Four sentences, front-loaded with primary action and domain list. Every sentence adds value: purpose, when to use, return format, and explicit instruction to call first. 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?

No output schema exists, but description fully explains return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)'. Given complexity as a discovery tool, this 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 has 100% description coverage with 6 parameters explained (query and aliases, limit). Description does not add new semantics beyond examples in schema examples. Baseline 3 is appropriate since schema does the work.

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

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

Description uses 'Find tools by describing the data or task' as a specific verb+resource, and lists many concrete domains (SEC filings, FDA drugs, etc.). It differentiates from siblings by stating it returns full schemas and examples ready to call, which other tools do not.

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 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context for when to use, though does not explicitly list when not to use or give alternative tool names.

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 readOnly, openWorld, idempotent, non-destructive. Description adds details about fanning across multiple sources, patents sunsetting May 2025 with soft-fail, and return 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?

The description is somewhat long but every sentence provides value. Starts with examples, states purpose, then lists return data. While effective, it could be slightly 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?

For a complex tool with multiple sources and no output schema, the description fully explains what is returned (filings, fundamentals, patents, news, LEI) and limitations (patents soft-fail). 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 covers 100% of parameters. Description adds context: ticker examples, CIK format, name unsupported, and type enum limitation. 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 clearly states the tool does 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and fields, distinguishing it from siblings like resolve_entity.

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 'ALWAYS PREFER over chaining single-pack lookups when user asks for holistic view' and advises using resolve_entity first if only a name is available. Provides example triggers.

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 destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and dealing with stale context, which is useful beyond annotations. 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 sentences, front-loaded with action, no wasted words. Highly efficient for conveying purpose and usage context.

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 simplicity of the tool (one param, no output schema), the description covers purpose, usage context, and pairing with siblings. Missing explicit mention of idempotency but overall adequate.

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

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

Schema coverage is 100% and description does not add meaning beyond what the schema already provides for the 'key' parameter. 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?

Clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. Distinguishes from siblings by naming 'remember' and 'recall' as paired tools.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Mentions pairing with siblings but does not specify when not to use or provide alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it fetches the page and extracts content, which is consistent and provides useful detail without 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?

Concise, two sentences followed by a bullet list of use cases. Well-structured, front-loaded, 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?

Given simple input schema (2 params, no output schema), the description adequately explains what the tool does and what the output is (a text blob). 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%, so baseline 3. The description mentions fetching page and extracting info, which aligns with parameters but doesn't add meaningful new semantics 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 it generates a llms.txt file for a URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on creating a standard file.

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 use cases (getting client's site indexed, drafting for own project, auditing competitor). However, lacks exclusions or when not to use, so not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context about return fields and the 'caller's' scope, reinforcing safety. 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: first covers purpose and output, second provides usage guidance. 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?

Complete for a low-complexity tool: purpose, return fields, usage context, parameter implication, and annotations cover rest. No output schema needed.

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

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

Schema coverage is 100% with a clear boolean description. Description doesn't add new parameter semantics beyond reinforcing the parameter's role in usage, but baseline is adequate.

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 verb 'List' and resource 'the caller's active subscriptions', and lists return fields. It distinguishes from siblings like '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?

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel'. No exclusions or alternatives mentioned, but 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 that the tool returns specific fields (name, category, material, image URLs), which is useful context beyond annotations. 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 a single, well-structured sentence. It front-loads the core action and key parameter, then enumerates return fields. 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?

Given the tool's simplicity (1 param, has output schema), the description covers essential details. It mentions returned fields, and the output schema can provide further structure. Adequate for an 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?

Schema description coverage is 0%, but the description explains that `part_num` is the identifier for the part, adding meaning beyond the schema's simple type declaration.

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

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

The description clearly states the tool fetches details for a single LEGO part by part_num, specifying returned fields (name, category, material, image URLs). This distinguishes it from sibling tools like 'parts' which likely list multiple parts.

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

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

The description implies use when you need a specific part's details, but lacks explicit comparison to siblings like 'parts' for listing or 'colors' for color-specific queries. No direct guidance on when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds return fields but no additional behavioral traits like pagination or ordering behavior.

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

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

Two sentences, front-loaded with purpose and return, followed by a usage tip. 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?

Despite output schema existing, the description fails to explain pagination and ordering parameters, which are essential for effective use. Many parameters lack any description.

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

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

With 0% schema description coverage, description must explain parameters. It covers 'query', 'color_id', and 'part_cat_id' but ignores 'page', 'page_size', and 'ordering', leaving them unspecified.

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 the tool searches Rebrickable LEGO parts by keyword, color_id, or part_cat_id, and lists return fields. Distinguishes from siblings like 'part' (singular) and 'colors'.

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 to use 'colors' or category list to get valid IDs, but does not explicitly state when to avoid this tool (e.g., for a single part, use 'part' tool). Still helpful.

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

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

The description adds behavioral context beyond annotations: the team reads digests daily, signal affects roadmap, rate-limited to 5 per identifier per day, and free/quota-free. Annotations only provide readOnlyHint=false, etc., without these details.

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

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

The description is concise (5 sentences) and well-structured: purpose first, then usage guidelines, then behavioral traits. Every sentence adds value with 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?

For a feedback tool with 3 parameters (2 required), a nested object, and no output schema, the description covers all necessary aspects: what to submit, how to format it, rate limits, and team responsiveness. It is complete 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%, and the parameter descriptions in the schema are already detailed (e.g., enum values, message format hints). The tool description does not add new semantic information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and resource, and clearly distinguishes from sibling tools (which include ask_pipeworx, etc., but no other feedback tool).

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

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

The description explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. It also provides specific guidance on how to describe the issue (in terms of Pipeworx tools/packs, not end-user prompts).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extra context: derived from CF analytics-engine, no PII, caching behavior (5min-1h). No contradiction.

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

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

The description is efficient: front-loaded purpose, three bulleted use cases, then technical details. No redundant phrases; 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?

Despite no output schema, the description mentions return fields (top tools, top packs, total call volume). It's nearly complete for a simple read-only tool, though the exact structure is not specified.

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

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

Schema covers 100% with one parameter (window, enum). Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema's description.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with a specific verb (calling) and resource (Pipeworx). It distinguishes itself from sibling tools like discover_tools and ask_pipeworx by focusing on aggregate trending data.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, seeing alignment). While it doesn't explicitly state when not to use the tool or name alternatives, the description gives strong contextual guidance.

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

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

Annotations declare readOnly, idempotent, non-destructive, and description adds detailed internal checks (semantic anchor, partition filter, fill check). 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?

Dense but well-organized: starts with summary, explains modes, then details. A bit wordy but necessary for complexity. Could benefit from bullet points.

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 covers response structure (opportunities array, partition_check, fill check) and refers to polymarket_fill_risk for sizing. Complete for agent 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 descriptions cover 100% of parameters, but description adds significant extra meaning: explains mode behavior, examples, and internal logic (e.g., Jaccard similarity, placeholder filtering).

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes two modes (event, topic) and a default trending scan, 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?

Explicit guidance when to use each mode: no args for trending, event for specific market, topic for cross-event. Provides examples and recommends event mode. However, lacks explicit 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?

The description goes far beyond annotations, disclosing caching, model families, edge calculation details, tradeable-edge knobs, and diagnostics. It explains how missing opportunities can be diagnosed. No contradictions with annotations (readOnly, idempotent, etc.).

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

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

The description is a dense paragraph but is well-structured with an opening purpose, breakdown of model families, response structure, and knobs. While comprehensive, it is slightly verbose due to technical jargon; however, every sentence serves a purpose given the tool's complexity.

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

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

Without an output schema, the description fully explains the response structure, including by_segment fields, edge details, and diagnostics. It also explains how knobs and filters affect output, making the tool's behavior completely understandable.

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

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

All 9 parameters are documented in the input schema with 100% coverage. The description adds significant value beyond schema, explaining the purpose and nuance of each parameter (e.g., slippage_pp context, min_partition_leg_kelly clarification).

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

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

The description starts with a specific verb+resource: 'Scan top Polymarkets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on disagreement with Pipeworx data and providing a comprehensive output structure.

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 the tool is built for 'what should I bet on today', identifying the use case. It implicitly suggests usage over alternatives by detailing the unique edge calculation. However, it lacks explicit when-not-to-use statements or direct comparisons to siblings, which would further strengthen guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral details: response structure (tracked, expired, snapshot_dates), decay computation from daily closes (not intraday), trend categories, and limitations (60-day TTL, snapshot-on-cache-miss). 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 fairly long but well-structured: explanation of purpose, response format with labelled fields, and limitations. Each sentence adds valuable information. Could be slightly more concise, but the density of useful content is high.

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 explains the response structure (tracked, expired, snapshot_dates) with details on fields, trend computation, and limitations. It covers all necessary aspects for an agent to understand input and output, making it complete for a tool with two optional parameters.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning by explaining 'window' as a snapshot family and 'days' as lookback with default and clamp (already in schema). It also clarifies the role of window in reading snapshots. This adds some value beyond the schema, justifying a score above the 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 clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling tools like polymarket_edges (which likely provides current edges) and polymarket_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 clear usage context with the example of a fresh wide edge vs an old wide edge, implying when this tool is valuable. It does not explicitly state when not to use it or list alternatives, but the context is sufficient for an AI agent to decide when to invoke this tool over others.

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 and idempotentHint. The description adds significant behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced_directional_risk and partial basket fills. No contradiction with annotations.

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

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

The description is long but well-structured with capitalized keywords (REQUIRES, SINGLE-MARKET, BASKET) and clear separation of modes. However, some redundancy exists (e.g., repeated warning about theoretical overround). Still, 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?

Despite no output schema, the description comprehensively lists return fields for both modes, explains verdict values, and highlights the key risk of partial fills converting arb to directional. It covers size clamp and default behavior, making it self-contained.

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

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

Schema description coverage is 100% but the description enriches parameter meaning beyond schema, e.g., explaining size_usd for buys vs sells, default side logic for basket, and the clamp range (10–1,000,000) not 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?

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by indicating when to use this tool before acting on those 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the consequences of not using it, such as thin books not capturable and partial fills converting arb to directional position.

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

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

The description extensively covers behavioral traits beyond annotations, including two modes, response structure, safety fields, compatibility_warning scenarios, temporal alignment, and skipped leg counters, with no contradiction to the read-only, open-world, idempotent hints.

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

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

The description is detailed and well-structured, front-loading the core purpose and then systematically explaining modes and safety. While it is somewhat lengthy, every sentence contributes value, with only minor redundancy.

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

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

Despite lacking an output schema, the description comprehensively explains the response structure, including per-venue prices, spread fields, safety indicators, temporal alignment, and counters, making the tool's behavior fully understandable.

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 each parameter; the description adds context by explaining the distinction between topic and explicit modes and provides example values, enhancing understanding 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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question, specifies two modes (topic shortcuts and explicit tickers), and differentiates from sibling tools by its specific focus.

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 guidance on when to use topic mode vs explicit mode, warns that most pre-mapped topics return compatibility warnings, and indicates that real spreads are rarer than the shortcut list suggests, though it does not explicitly list when not to use it.

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

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

Description adds scope detail (anonymous IP, BYO key hash, account ID) beyond readOnlyHint and idempotentHint annotations. Could mention rate limits but adequate.

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 the core action, then usage, scope, and pairing. No wasted words, 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?

Complete for a simple retrieval tool. No output schema, but description covers key behaviors. Could mention return format but not critical.

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. The tool description complements by explaining the behavior when key is omitted (list all). Adds 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 retrieves a value or lists all keys, using specific verbs. It distinguishes itself by naming paired tools (remember, 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?

Explicitly states when to use: to look up stored context without re-deriving. Mentions scoping and pairing. Lacks explicit 'when not to use' but sufficient given sibling 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?

The description discloses that setting mark_read:true flags events as read, which is a state-mutating operation. However, annotations declare readOnlyHint:true and idempotentHint:true, which contradict this mutation. This is a clear annotation contradiction, warranting a score of 1.

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 with about 4 sentences, front-loading the main purpose and then adding usage details efficiently. Every sentence adds value without redundancy.

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

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

No output schema exists, but description informs about return fields (source, citation_uri, raw payload). It covers optional parameters, polling behavior, and alternative access method. The tool is well-contextualized for agent usage.

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. Description adds value by explaining how mark_read affects subsequent calls and providing example values for type and since, going beyond the schema's basic descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed and returns recent alerts with specific fields. It distinguishes the tool's function but does not explicitly differentiate from siblings like 'list_subscriptions' or 'recent_changes', though the verb 'pull' and resource 'alerts' 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?

Description provides explicit when-to-use guidance with filtering examples (type, since), mark_read usage, and an alternative REST endpoint for scripts/dashboards. It tells the agent how to get only newer events after marking read.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral context: the parallel fan-out to multiple sources, fallback logic, acceptance of both ISO dates and relative shorthand, and the structure of the returned data (grouped changes, total count, citation URIs). No contradictions with annotations.

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

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

Three sentences: the first provides example queries and the core purpose, the second describes the multi-source parallel call with fallback details, and the third explains parameter syntax and directs to the sibling tool. Every sentence adds unique value with no redundancy or fluff.

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

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

Despite no output schema, the description covers the return shape (structured changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It fully explains input parameters, source behavior including fallbacks and soft-fail, and when to use the alternative entity_profile—complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds valuable nuance: it explains that 'since' accepts ISO dates or relative shorthand (with examples like '7d', '30d'), recommends '30d' or '1m' for typical use, and clarifies that 'value' can be a ticker or zero-padded CIK. The 'type' parameter's limitation to 'company' is also stated, going beyond the schema's enum.

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

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

The description opens with concrete example queries ("What's new with X", "latest on Y"), immediately clarifying it provides a change feed over a recent window. It enumerates specific data sources—SEC EDGAR, GDELT/GNews fallback, USPTO—and explicitly distinguishes itself from the sibling entity_profile tool, leaving no ambiguity about its scope.

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

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

The description gives clear guidance: use for time-bound 'what's new' queries and explicitly states when to use entity_profile instead (static profile regardless of window). It also details the fallback behavior (GDELT preferred, GNews on rate limit/5xx) and soft-fail for USPTO, helping the agent decide confidently.

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 explains scoping by identifier and persistence details (authenticated users persistent, anonymous 24 hours), which goes beyond annotations. No contradiction with annotations (idempotentHint is consistent with key-value storage).

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?

Five concise sentences, front-loaded with purpose, logically organized: purpose, usage examples, storage mechanics, persistence, companion tools. No redundant 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?

Fully covers purpose, usage guidance, parameter context, persistence, and inter-tool relationships. No significant gaps given tool simplicity and absence of output schema.

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

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

Schema coverage is 100% with good descriptions. The description reinforces the purpose with examples and clarifies usage context (e.g., 'findings, addresses, preferences, notes'), adding 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 clearly states it 'save data the agent will need to reuse later' across conversations and sessions. It uses a specific verb-resource pair and distinguishes from sibling tools like 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?

Provides explicit guidance: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Mentions pairing with recall and forget for retrieval and deletion.

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, openWorld, idempotent, non-destructive. Description adds that each call cascades through multiple lookup endpoints internally and details return values for each type, providing useful behavioral 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?

Well-structured: starts with example queries, then purpose, usage recommendation, supported types. Each sentence adds value, though slightly verbose. Could be tightened slightly.

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 entity types, cascading lookups) and lack of output schema, description adequately explains what is returned and how it works. Missing error/limits info, but overall complete enough.

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

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

Schema coverage is 100%, baseline 3. Description adds concrete examples for the 'value' parameter (ticker, CIK, name for company; brand/generic for drug) and explains return fields, enhancing understanding 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?

Description uses specific verbs like 'resolve' and 'look up', clearly states it maps names to canonical IDs, and distinguishes from siblings (no other tool does entity resolution). Example queries and explicit 'Use FIRST' guidance reinforce 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID' and mentions it replaces 2-3 manual lookups. However, lacks explicit 'when not to use' or direct alternatives; context implies differentiation but could be stronger.

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 safe, read-only, idempotent behavior. The description adds that it returns a ranked list with score, confidence, signal density, and that it calls ai_visibility_check. It does not mention rate limits or privacy implications, but provides good context.

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

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

Three sentences with no wasted words. The first sentence states the main purpose, second explains mechanics, third gives a use case and output summary. Very efficient.

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

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

Without an output schema, the description adequately describes the output (ranked list with score, confidence, signal density). It covers input parameters, behavior, and output. For a tool with 4 parameters, it is reasonably complete, though a brief mention of error cases would improve it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it states the first entity is the 'subject' for narrative, context disambiguates, models specifies which AI models, and _apiKey is required for anthropic. This adds significant 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 it compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes and ranking. This distinguishes it from the sibling ai_visibility_check which probes a single entity.

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 it's useful for competitive AI-marketing audits and gives an example question. It implies using ai_visibility_check for a single entity, but does not explicitly state when not to use this tool or provide alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral traits: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts, and the rest still returns. 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 long but well-structured: purpose, usage, return format, limitations, edge cases. Every sentence adds value, though slightly wordy. Front-loaded with the main action and use case.

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 (composite call, no output schema), the description fully explains the return format (summary block fields, per-advisory detail, links, alternative versions) and handles edge cases (partial failures, timing). No gaps remain.

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 minor context (scoped packages accepted, version defaults to latest), but these are already captured in the schema descriptions. No significant additional meaning 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 clearly states the tool is a composite check for npm packages combining deps.dev and bundlephobia data, with a specific use case: 'should I add this npm package to my project'. It distinguishes from siblings by explicitly mentioning it's a single call that fans out across multiple sources.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing an alternative.

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

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

Reveals technical details: embedding model (BGE-base-en), windowing (500-char overlapping), truncation at 200K chars (with flag), and output format (top-N passages with offsets and similarity scores). Annotations already indicate safe read, but description adds significant behavioral context.

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

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

Five concise sentences, each adding essential information. Front-loaded with purpose, followed by usage and technical details. No redundant or vague language.

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 fully explains return values (passages, offsets, similarity scores) and covers edge case (truncation with flag). Also ties to sibling tool for grounded follow-up. Complete for a 3-param 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 descriptive parameter descriptions. Description adds context like 'text you already pulled' for text param and example queries for query param. Explains limit default and range indirectly. Goes beyond baseline by elaborating on parameter usage.

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?

States specific verb 'search' and resource 'inside a fetched record'. Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and noting it saves context for large records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides alternative workflow with ask_pipeworx_grounded, giving 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the data source (Rebrickable) and specific return fields, which goes beyond annotations. It does not contradict annotations.

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

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

The description is two sentences: the first states the action and parameter, the second lists return fields. No extraneous words. All information is front-loaded and relevant.

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

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

Given the tool's simplicity (one parameter, clear output schema present), the description is complete. It explains the purpose, input format, and output fields adequately for an agent to invoke correctly.

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

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

The input schema has one required parameter (set_num) with 0% schema description coverage. The description compensates fully by providing an example ('75192-1') and clarifying the expected format. This adds significant 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 the tool fetches a single LEGO set by set_num, specifies the source (Rebrickable), and lists the returned fields (name, year, theme, part count, image URL). This distinguishes it from sibling tools like 'sets' (plural), 'set_parts', and 'set_minifigs'.

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 primary use case (fetching a single set by set_num) but does not provide explicit guidance on when not to use it or mention alternatives. While sibling names imply distinctions, the description lacks direct 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 indicate idempotentHint=true and destructiveHint=false, aligning with the fetch operation. The description adds context about return fields but omits details like authentication requirements or rate limits. 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 two sentences, front-loading the action and resource. Every sentence is substantive and avoids fluff.

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

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

Given the presence of an output schema, the description appropriately lists the returned fields. No mention of pagination or errors, but for a simple fetch tool this is sufficient.

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

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

The parameter 'set_num' is described as a LEGO set number, adding minimal context beyond the schema. The schema provides an example but the description does not elaborate on format or constraints. With 0% schema coverage, the description partially compensates.

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 'Fetch' and the resource 'minifigures included in a LEGO set', distinguishing it from sibling tools like 'set_parts' (parts) and 'sets' (list sets). The source 'from Rebrickable' adds specificity.

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

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

The description implies use when needing minifigs for a specific set, but does not explicitly state when to use this versus alternatives like 'set_parts' or 'set'. No when-not-to-use guidance is provided.

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 idempotent and non-destructive behavior. The description adds value by specifying the returned fields (part_num, name, color, quantity, image URL), providing useful 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?

The description is a single clear sentence with no waste, front-loading the key action and resource.

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

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

The tool is simple with one parameter and the description adequately explains output fields. With output schema present, the description covers enough for selection and invocation.

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

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

Schema coverage is 0% and the description only mentions 'by set_num' without adding format details or examples. The schema has an example '75368-1' but the description does not reference it. Given the single parameter, more guidance would be helpful.

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 fetches the full parts list for a LEGO set by set_num from Rebrickable, with specific verb and resource. It distinguishes from sibling tools like 'set_minifigs' which focus on minifigs.

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 implicitly guides when to use: when you need parts for a LEGO set. However, it does not explicitly mention alternatives or when not to use.

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

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

Annotations already convey readOnly, idempotent, and non-destructive nature. The description adds that it returns specific fields but no additional behavioral traits like pagination behavior or rate limits.

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 wasted words; front-loaded with core purpose and immediately actionable.

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

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

Despite having an output schema, the description omits crucial details about pagination (page, page_size) and ordering, which are essential for effective use of this 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?

With 0% schema description coverage, the description must compensate but only loosely mentions keyword, theme_id, year range, and part count range as filters. Parameters like page, page_size, and ordering are not explained, leaving 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 'Search Rebrickable LEGO sets' and lists filtering options (keyword, theme_id, year range, part count range) and return fields, distinguishing it from related tools like 'set', 'parts', and 'themes'.

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 advises using the 'themes' tool for valid theme IDs, providing actionable guidance. However, it does not explicitly state when to use this tool versus alternatives like 'set' for a single set.

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

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

The description details behavioral traits beyond annotations: requires OAuth account, returns subscription ID, delivery channels with constraints (SMS rate limit, webhook signing, auto-disable), and side effects (webhook secret returned once). 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 longer due to detailed explanations, but every sentence adds value. It is front-loaded with the core purpose and structured with examples. Could benefit from bullet points for readability, but remains functional.

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 covers return value ('Returns the new subscription id'), authentication, delivery behavior, and limitations. It equips an AI agent to invoke the tool correctly and understand side effects.

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?

Despite 100% schema coverage, the description adds significant meaning: explains each subscription type with examples, details delivery options (email, SMS, webhook) with operational constraints (phone verification, rate cap, HMAC signing). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the action (create), resource (subscription), and distinguishes it from siblings like 'list_subscriptions' 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?

The description provides clear context for use, including authentication requirements (Pipeworx OAuth account) and supported subscription types. While it doesn't explicitly contrast with sibling tools like 'recent_alerts', the context is sufficient for an AI agent to infer appropriate use cases.

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, so the safety profile is clear. The description adds context that the tool returns 'category-bucketed example questions... drawn from the live catalog of thousands of tools', which implies dynamic content but doesn't contradict annotations. No behavioral 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 structured with a clear purpose first (alternative phrasings), then returns, then usage instructions. It is informative without being verbose. A minor improvement could be to trim the list of categories, but it remains concise overall.

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

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

Given no output schema, the description sufficiently explains what the tool returns: category-bucketed example questions with exact tool and argument shape. It covers the single optional parameter and its effect. This is complete for an onboarding tool that guides initial exploration.

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 mentions topics like 'finance', 'pharma', 'betting' as examples, but the schema already lists the valid focus areas. The description does not add substantial meaning beyond the schema, hence a 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 starts with a list of alternative phrasings that clearly define the tool's purpose: to suggest example questions for Pipeworx. It explicitly states it is the 'onboarding entry point' and returns 'category-bucketed example questions' with tool+argument shapes. This distinguishes it from siblings like ask_pipeworx, which answer questions, not suggest 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 provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with no arguments for full spread or with a topic to focus, giving clear, actionable instructions.

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 readOnlyHint, idempotentHint, and destructiveHint, so the description adds minimal new behavioral info beyond stating it returns the complete list. 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 sentences, front-loaded with the main action, and no extraneous 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 zero-parameter tool with annotations and a described output, the description is complete. It explains the purpose, return fields, and usage 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?

There are zero parameters and 100% schema coverage, so baseline is 4. The description does not need to add parameter semantics.

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

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

The description uses specific verbs ('Return') and resource ('complete list of LEGO themes'). It provides examples and states the return fields (id, name, parent_id). It distinguishes from sibling tools like 'sets' by explaining its use for filtering.

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

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

The description explicitly states when to use the tool: 'Use to get valid theme_id values for filtering `sets`.' This gives clear context, though it could explicitly mention when not to use it 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?

Describes that the row is deactivated not deleted, and that historical events remain available via 'recent_alerts'. Adds context beyond annotations, aligning with idempotentHint and destructiveHint.

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 efficiently cover purpose and key behavioral trait. No wasted words; front-loaded with the core action.

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

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

For a simple one-parameter mutation tool, the description explains effect on data, ownership constraint, and cross-reference to related tool. Complete given no output schema.

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

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

Schema covers the 'id' parameter with description 'Subscription id (uuid) returned by subscribe.' Description does not add further semantic detail, but schema coverage is 100% so baseline 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id', with a specific verb and resource. Differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by indicating deactivation instead of deletion.

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

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

Explicitly states when to use (cancel own subscription) and implies ownership constraint. Does not explicitly list when not to use, but behavioral details hint at alternatives like 'recent_alerts'.

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 safe read-only, idempotent, and non-destructive behavior. The description adds significant behavioral context: verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), routing logic, exact percent-delta math for financial claims, and citation format. 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 a single well-written paragraph that front-loads purpose with examples. It is dense but not excessively long. Minor improvement would be adding structure (e.g., bullet points for verdict types) to improve readability.

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

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

For a tool with no output schema, the description comprehensively covers input handling, routing logic, verdict types, evidence format, and reasoning. It provides enough detail for an agent to understand the full behavior and expected output.

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

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

Schema coverage is 100% and both parameters are described. The description adds extra meaning beyond the schema: it explains that tolerance_pct overrides the implied tolerance, provides example values for hallucination detection (1-2%), and clarifies default behavior ('implied by wording, capped at 5').

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

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

The description clearly states the tool's purpose with multiple natural-language examples (e.g., 'fact check', 'verify the claim') and explicitly distinguishes it from sibling tools by explaining how it replaces 4-6 sequential calls and routes financial vs. other claims.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). No explicit when-not-to-use or named alternatives, but usage context is clear.

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