Discogs

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

Annotations indicate readOnly=true, openWorld=true, idempotent, non-destructive. The description adds value by noting that Anthropic calls require a BYO key and incur direct costs. It also describes the return structure (per-model score, confidence, signals, raw_response + combined view), which goes beyond annotations.

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

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

The description is three sentences, each providing essential information: purpose, default behavior with cost note, and use cases. No redundancy, well front-loaded.

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

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

Despite no output schema, the description explicitly lists the components of the return value (per-model {score, confidence, signals, raw_response} + combined view). This is complete for a probing tool, and the cost implication is noted.

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

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

With 100% schema coverage, the description still adds meaning: it clarifies that 'models' defaults to workers-ai, '_apiKey' is only needed for Anthropic, and 'context' disambiguates. This enriches the schema documentation.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business / brand / product / topic') and clearly distinguishes visibility scoring. It is distinct from sibling tools like 'ask_pipeworx' or 'entity_profile'.

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

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

The description states when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the default model and optional Anthropic probing. It does not explicitly list when not to use, but the context is clear.

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

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

With no annotations, the description carries full burden. It discloses that the tool routes across many sources, picks the right tool, and fills arguments. However, it does not mention error handling, ambiguity, or any safety considerations like rate limits or read-only nature.

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

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

The description is front-loaded with purpose, then usage guidelines and examples. Every sentence adds value, though it could be slightly more concise by trimming redundancies like the long source list.

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

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

Given the single parameter and no output schema, the description adequately covers functionality, usage context, and examples. It does not explain return format, but that is common for such query tools. It feels complete for the tool's scope.

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 one 'question' parameter described clearly. The description adds value by providing example questions and stating the parameter is a natural language request, which goes beyond the schema's generic 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 answers natural-language questions by automatically picking the right data source. It gives specific verb-noun patterns like 'What is X?' and lists over 300 sources, making its purpose distinct from siblings like specific get_artist or search tools.

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

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

The description explicitly states when to use: 'when a user asks... and you don't want to figure out which Pipeworx pack/tool to call.' It provides examples. However, it does not explicitly mention when not to use or name alternatives like the specific get 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 declare readOnlyHint=true and destructiveHint=false, so description is not required to restate safety. The description adds behavioral context about fanning out to packs (e.g., crypto+fred+gdelt) and returning comparisons. No contradictions, and it provides useful non-obvious behavior.

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

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

The description is descriptive but front-loaded with the main purpose. Every sentence adds value, though it could be slightly more concise. Length is justified by the complexity of the tool's fan-out logic.

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 briefly explains the return format (evidence packet plus market-vs-model comparison). It covers input, process (fan-out to packs), output, and use cases comprehensively for a tool with two parameters and clear annotations.

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

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

Schema coverage is 100% for both parameters. The description adds value beyond schema by explaining the depth parameter semantics ('quick = 2-3 evidence sources, thorough = full fan-out') and giving examples for the market parameter. This helps the agent understand parameter behavior.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question) and output (evidence packet, market-vs-model comparison). It distinguishes itself from siblings by focusing on Polymarket bets, while siblings like ask_pipeworx or validate_claim serve different purposes.

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

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

The description provides explicit use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', or 'is there edge in this bet?'. It does not explicitly state when not to use or list alternatives, but the use cases are clear and cover the intended 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?

With no annotations, the description carries the full burden. It discloses data sources (SEC EDGAR/XBRL for companies, FAERS etc. for drugs) and output format (paired data + citation URIs). Minor omissions like real-time vs cached data prevent a higher score.

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

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

The description is compact but covers all key points. It front-loads the main purpose and uses examples effectively. A few sentences could be tightened, but overall it is efficient.

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

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

Given no output schema, the description adequately explains the return format and data sources. It covers both entity types and usage scenarios comprehensively, making it complete for an agent to decide when and how to invoke.

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

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

Schema coverage is 100%. The description adds value by explaining what each type pulls (financial metrics vs adverse events) and giving examples for values (tickers vs drug names), going beyond 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 compares 2–5 companies or drugs side-by-side. It gives specific verb and resource, and distinguishes from sibling tools like 'entity_profile' and 'search' by focusing on comparison.

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

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

The description provides explicit usage triggers such as 'compare X and Y' and 'X vs Y', and notes efficiency gains. However, it does not mention when not to use this tool or suggest 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?

No annotations provided, so description must carry burden. States it returns top-N relevant tools with names and descriptions, but does not disclose if it's read-only, rate limits, or side effects. Adequate but could be more explicit.

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?

Single paragraph front-loaded with main action, but slightly wordy with many examples. Still efficient, no redundant sentences.

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?

Simple tool with no output schema or nested objects; description covers purpose, usage, and parameters sufficiently. Lacks details on ranking but acceptable for discovery tool.

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

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

Schema coverage is 100% (baseline 3). Description adds examples for query and default/max for limit, but doesn't significantly extend beyond 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?

Description states 'Find tools by describing the data or task' with clear examples, distinguishes from sibling tools like 'ask_pipeworx' or 'search' by focusing on discovery.

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

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

Explicitly says when to use: browsing, searching, discovering tools, and advises calling this first when many tools are available. Lacks explicit alternatives or when-not-to-use, but guidance is strong.

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

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

Discloses returned data categories and citation URIs, but does not discuss rate limits, data freshness, or potential delays. However, it is sufficient for a read tool with no annotations.

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

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

Two concise sentences covering purpose, use cases, return contents, and input specifics without unnecessary words.

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

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

With no output schema, the description thoroughly lists what is returned (filings, financials, patents, news, LEI) and even notes citation format. Covers input constraints and alternatives.

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?

Adds meaningful details beyond schema: explains 'type' enum limitation and 'value' alternatives (ticker vs CIK) and why names are unsupported.

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?

Starts with a clear verb+resource ('Get everything about a company in one call') and lists specific use cases. Distinguishes from siblings like search and compare_entities.

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

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

Explicitly states when to use ('tell me about X', etc.) and when not to use (names not supported), with a direct pointer to sibling tool resolve_entity.

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

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

No annotations provided, so description must carry behavioral burden. It indicates destructive action but lacks details on error behavior (e.g., key not found) or idempotency.

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 succinct sentences: one defining action, one providing usage guidance. No redundant 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?

Covers purpose, usage, and sibling context. Lacks mention of return value or confirmation, but adequate for a simple delete operation.

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

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

Schema has 100% coverage for the single 'key' parameter. Description adds no extra meaning beyond what schema provides.

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 verb (Delete), resource (memory), and method (by key). Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly provides three use cases: stale context, task completion, sensitive data clearing. Also references sibling tools for 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 (readOnlyHint, idempotentHint, destructiveHint) indicate a safe, non-destructive read operation. The description adds behavioral details: fetches page, extracts title/description/key links, emits standard markdown. No contradictions.

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

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

Two sentences plus a bulleted list of use cases. Every sentence adds value, no filler. Front-loaded with the core action and output.

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

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

No output schema, but the description explains the output is a single text blob for site-root/llms.txt. Covers input, process, output, and use cases. Complete for a simple generation tool.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add new parameter-level details but provides useful context about the output format. Baseline 3 is appropriate as schema covers semantics well.

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

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

The description explicitly states the tool generates an llms.txt file for any URL, a specific verb-resource combination. It distinguishes itself from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on llms.txt generation.

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

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

The description lists three concrete use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. It provides clear context but does not explicitly state when not to use or mention 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?

With no annotations, the description carries full burden. It fails to disclose behavioral traits like read-only nature, error handling (e.g., missing ID), or rate limits. The terse description provides minimal transparency.

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

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

The description is extremely concise (4 words), but this sacrifices clarity. While no waste, it is under-specifying for a tool that likely returns complex data. A slightly longer description would improve value.

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

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

Given the simple input schema (single parameter) and no output schema, the description is minimally complete. It conveys the tool's purpose for an 'artist profile' but lacks details on output structure or behavior, leaving gaps.

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

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

Schema coverage is 100% with a single parameter 'artist_id' described as 'Discogs artist ID'. The description adds no extra meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description 'Artist profile + identifiers' clearly indicates the tool retrieves artist data, distinguishing it from sibling tools like get_label or get_release. However, it omits specifics about what 'profile' includes, making it only moderately clear.

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

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

No guidance is provided on when to use this tool versus alternatives such as search or entity_profile. The description offers no context for preferred usage.

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

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

Annotations are absent, so the description must convey behavioral traits. It only states outputs but fails to disclose that the tool is read-only, its impact on data, or any rate limits. This is insufficient for a tool with no annotation support.

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 very concise (one sentence) but lacks a clear verb and front-loading. While short, it could be restructured for better readability without adding length.

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

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

Given no output schema, the description should provide more context about return values, error handling, or usage notes. It is incomplete for a 'get' tool, leaving the agent to infer behavior from the name alone.

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

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

With 100% schema coverage, the parameter 'label_id' is documented. The description adds minimal extra meaning, only hinting at the output structure. Baseline 3 is appropriate as the schema already handles parameter documentation.

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 'Label profile + parent label + sublabels' indicates the tool returns label information, but lacks a verb like 'retrieve' or 'get'. It is somewhat vague and does not strongly differentiate from siblings like 'get_artist' or 'get_release', though the name itself implies the entity type.

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

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

No usage guidelines are provided. There is no indication of when to use this tool versus alternatives such as 'get_artist' or 'get_master', nor any prerequisites or limitations.

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

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

No annotations are provided, so the description must carry the burden. It fails to disclose read-only nature, error behavior, or any side effects. Only the core purpose is stated.

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?

A single, well-structured sentence that immediately identifies the tool's purpose. 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?

Adequate for a simple lookup with one parameter, but the lack of output schema means the description should hint at return content. 'Detail' is vague.

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

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

Schema description coverage is 100%. The description adds no extra meaning about the parameter beyond the schema definition, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool retrieves master release details and defines a master as the canonical work across editions. It implicitly distinguishes from sibling like get_release, but does not explicitly name alternatives.

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

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

No guidance on when to use this tool vs alternatives such as get_release. The agent must infer from the name and description alone, which is insufficient for correct selection.

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

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

No annotations exist, so the description must carry the burden. It lists returned fields but does not mention behavioral traits like read-only nature, authentication needs, 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?

The description is a single sentence that efficiently lists all relevant details without any extraneous 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 no output schema, the description compensates by listing numerous return fields. However, it omits potential error conditions or optional parameters, leaving minor gaps.

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

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

Schema coverage is 100% and the parameter description is clear ('Discogs release ID'). The description adds no extra meaning beyond the schema, meeting baseline.

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

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

The description uses 'Full release detail' as the verb and clearly lists the specific content (artists, labels, tracklist, etc.), distinguishing it from sibling tools like get_artist or get_master.

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

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

The description implies usage for retrieving release details but provides no explicit when-to-use, when-not-to-use, or alternatives. It is adequate but lacks 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?

No annotations provided, but the description fully discloses behavioral traits: feedback is read daily by the team, affects roadmap, rate-limited to 5 per identifier per day, and doesn't count against tool-call quota. It also instructs to describe in terms of tools/packs, ensuring actionable feedback.

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 well-structured paragraph that front-loads purpose, then usage, then details. Every sentence is meaningful, though it could be slightly more concise; a clear and efficient format 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 the tool has 3 parameters (including nested object) and no output schema, the description covers all essential aspects: purpose, usage guidelines, behavioral constraints (rate limit, quota), and parameter semantics. It is fully 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 coverage is 100%, and the description adds meaning by explaining the 'type' enum values in more context and providing guidance on filling 'message'. The optional 'context' object is explained with examples, enriching 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 is for giving feedback about bugs, features, data gaps, or praise to the Pipeworx team. It specifies the types of issues and how to describe them, distinguishing it from sibling tools that are for data retrieval or actions.

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 a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or when something worked well (praise). Also provides what not to do (don't paste end-user prompt) and mentions rate limits and quota exemption.

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

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

Description adds significant behavioral context beyond annotations: explains data derivation (CF analytics-engine), states no PII, and mentions caching (5min-1h). No contradiction with readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false.

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?

Paragraph is well-structured with a lead sentence then bullet-like use cases. No fluff, but could be slightly tighter. Front-loads core function.

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

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

Tool has no output schema, but description adequately describes return values (top tools, packs, volume). Input is simple (one param). Annotations cover safety. Complete for an agent to decide and invoke.

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

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

Schema already provides enum and description for 'window' parameter (100% coverage). Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand' and notes default 24h, improving selection guidance.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window, with specific verb 'returns' and resource nouns. It uniquely distinguishes from siblings (e.g., search, entity_profile) by focusing on aggregated 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?

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, aligning use case). Does not name alternative tools but implies when to use (trending info) and when not (specific queries).

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 complements annotations (readOnlyHint, openWorldHint) by detailing the internal process: walking child markets, extracting dates/thresholds, sorting, and reporting violations. It does not contradict annotations and provides full transparency on what the tool does.

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

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

The description is well-structured, starting with the purpose, explaining the rationale, then the action, and ending with return format. It is slightly lengthy but each 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 lacking an output schema, the description sufficiently explains the return structure (market_a, market_b, gap_pp, suggested_trade). The concept of arbitrage via monotonicity is fully explained, making the tool's behavior complete for an agent.

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

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

The input schema has 100% coverage for the single parameter 'event' with a clear description. The tool description adds some context (e.g., the mechanism of walking markets) but does not significantly enhance the parameter semantics 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 finds arbitrage opportunities by checking monotonicity violations within a Polymarket event. It explains the logic with an example and distinguishes itself from sibling tools like polymarket_edges by specifying its focus on event-level 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 explains when to use the tool: when an event has multiple by-date or by-threshold markets. It provides context on the monotonicity rule but does not explicitly mention when not to use it or alternatives, though the purpose is clear enough.

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

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

Beyond readOnlyHint and destructiveHint, description details the algorithm (scans top markets, groups by asset, fetches price history, computes model probability, ranks by |edge|) and scope (V1 covers crypto-price bets). 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?

Description is a single paragraph of five sentences, front-loaded with key information. Each sentence adds value: purpose, model, process, output, and intended use. No redundant or extraneous content.

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

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

Given the tool's moderate complexity and absence of output schema, the description covers all essential aspects: inputs, algorithm steps, output format (top N with suggested direction), and limitations (V1 scope). Annotations supplement safety profile. Sufficient for agent 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?

All three parameters have full schema descriptions (100% coverage), so baseline is 3. The tool description provides operational context (e.g., how limit affects output) but does not add new semantic details beyond what the schema already conveys.

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 'Scan the highest-volume Polymarket markets and return the ones where Pipeworx data disagrees most with the market price', specifying verb, resource, and unique value proposition. Differentiates from sibling 'polymarket_arbitrage' by focusing on edge detection for a specific use case.

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

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

Describes tool as built for 'what should I bet on today' and helping users discover opportunities without manual browsing, which implies when to use. Lacks explicit exclusion criteria or comparison to sibling tools, but context is clear enough for most agents.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds value by explaining the return format (leg-by-leg prices in 0-1 range, spread in percentage points) and the two operational modes, which are behavioral traits beyond the 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?

The description is well-structured and front-loaded with the core purpose. It efficiently conveys the arb signal explanation, two modes, and return format with minimal redundancy. Slightly verbose in the middle, but every sentence adds value, earning a score above average.

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 return values (prices and spread). It covers both modes and parameter interactions. However, it lacks explicit handling of edge cases like providing only one explicit parameter, but overall is complete for a read-only data tool.

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

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

Schema coverage is 100% with each parameter described, but the description enriches semantics by explaining that topic is a pre-mapped shortcut and that explicit parameters override the topic-mapped side. It also clarifies that all parameters are optional and how modes interact, adding 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 explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishes it from siblings like polymarket_arbitrage through specific mention of venue pairing, and clearly outlines two operational modes (topic shortcuts vs explicit ticker/slug). It uses specific verbs and resources.

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

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

The description provides clear guidance on when to use each mode (topic for pre-mapped macros, explicit for custom pairings) and explains the interaction between parameters (explicit overrides topic). However, it does not explicitly state when not to use this tool or mention alternatives like polymarket_arbitrage.

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

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

No annotations provided, so description must carry full burden. It discloses basic behavior (retrieve or list) and scoping, but lacks details on error handling (e.g., missing key) or safety guarantees (read-only).

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 well-structured, front-loaded sentences. Efficient but could be slightly tighter 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 the tool's simplicity (one optional param, no output schema), the description covers purpose, usage, scoping, and pairing with siblings. Missing return format is minor.

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

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

Schema has 100% coverage for the single parameter; description adds context by explaining omission lists all keys and providing use cases, 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 the tool retrieves saved values or lists all keys, with specific examples (ticker, address, notes) and distinguishes from sibling tools remember and forget.

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

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

Provides clear context for when to use (look up stored context) and mentions scoping, but does not explicitly state when not to use or name alternative tools beyond remember/forget.

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?

With no annotations, the description carries full burden. It discloses parallel fan-out to three sources, return content, and citation URIs. It does not mention read-only nature or rate limits, but the level of detail is good.

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 paragraph that is fairly concise, each sentence adds information. Could be slightly more structured (e.g., bullet points for sources), but it is efficient and front-loaded.

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

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

Given no output schema, the description explains the return format (structured changes, count, URIs) and covers all parameters. It provides enough context for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so the description adds value by explaining the type constraint, providing examples for since (ISO or relative), and suggesting default values. It also clarifies value can be ticker or CIK.

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 recent changes for a company from SEC, GDELT, and USPTO. It provides example queries that illustrate the use case, and distinguishes it from siblings like entity_profile by focusing on temporal changes.

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 tells when to use this tool (e.g., user asks about updates or what's happening) and gives example phrases. Although it doesn't directly contrast with siblings, the use case is clearly defined.

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?

Discloses scoping by identifier, retention policies (persistent for authenticated, 24-hour for anonymous), and pairing with other tools. No annotations needed.

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?

Compact, front-loaded with purpose, every sentence adds value, no fluff.

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

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

Covers purpose, usage, storage details, and pairing; complete for a simple two-param tool with 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 descriptions cover both parameters, and the description adds context about key-value pair usage and examples, reinforcing meaning.

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

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

The description clearly states the tool saves data for reuse, specifies the resource (key-value memory), and distinguishes from siblings 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?

Explicitly says when to use ('when you discover something worth carrying forward'), and pairs 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?

No annotations provided, so description carries full burden. It states 'look up' implying read-only, and mentions return of IDs and URIs, but does not explicitly disclose auth needs, rate limits, or other behavioral traits.

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 roughly 4 sentences, front-loaded with purpose and usage. Every sentence adds value, 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?

With 2 required params and no output schema, the description covers purpose, usage, examples, and return type. Could mention error behavior or input format variations, 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%, baseline 3. The description adds meaning with examples for both parameters, explaining the value parameter in more detail than 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 states 'Look up the canonical/official identifier for a company or drug' with a specific verb and resource. It distinguishes from siblings by noting it replaces 2-3 lookup calls and provides IDs needed by other tools.

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

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

The description explicitly says 'Use when a user mentions a name and you need the CIK...' and 'Use this BEFORE calling other tools that need official identifiers.' No explicit when-not, 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?

All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) already declare safety. Description adds operational details: probes each entity, ranks by score, returns list with score/confidence/signal density. 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?

Three sentences: purpose, operation, use case. No wasted words, front-loaded with key info. Efficient and effective.

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

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

Given 4 parameters fully described in schema, annotations cover safety, description explains output format (ranked list with score/confidence/density). No output schema, but description compensates. Lacks failure/rate limit info, but not critical for this type of 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 100%. Description adds value beyond schema: explains that first entity is treated as 'subject' for narrative, and context disambiguates. Adds meaning that is not in 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?

Clearly states verb+resource: 'Compare AI visibility across multiple entities side-by-side.' Differentiates from siblings like ai_visibility_check (single entity) and compare_entities (general comparing) by specifying competitive AI-marketing audits and ranking.

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

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

Clearly describes when to use (competitive audits, comparing AI visibility). Does not explicitly state when not to use, but context makes it clear. Could explicitly contrast with single-entity tools, but still strong.

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

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

Description communicates it's a read operation but not much beyond that. No annotations exist to fill gaps. It does not disclose pagination behavior or response format, leaving some behavioral aspects unspecified.

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

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

Two sentences: first defines purpose with verb and scope, second lists filters. Perfectly front-loaded with no extraneous 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 12 parameters, 1 required, no output schema, and no annotations, the description covers the basics but lacks details on response structure, pagination, or filter combination logic. Adequate but leaves room for improvement.

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

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

Schema coverage is 100% with each parameter already described. The description adds minimal new information by listing some filter examples (e.g., 'Vinyl', 'CD') but these are also present in schema descriptions. Baseline 3 is appropriate.

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

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

Description clearly states the tool performs full-text search across specific Discogs entity types (releases, masters, artists, labels) and lists available filters. This is specific and distinguishes it from sibling tools like get_artist or get_release which fetch individual 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?

The description implies use for broad searches across entities, but does not explicitly state when to prefer this over sibling tools (e.g., get_artist for exact ID lookups). 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?

With no annotations, the description carries full burden. It discloses return values (verdict types, structured form, actual value with citation, percent delta) and data sources (SEC EDGAR + XBRL). However, it could be more detailed about limitations, error handling, or latency, but overall is fairly transparent.

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: four sentences with no fluff. First sentence defines purpose, second gives usage, third covers scope and source, fourth covers output and efficiency. Information is front-loaded and well-structured.

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

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

Given the tool's complexity, the description adequately covers purpose, input, output, scope, and efficiency benefits. It explains the return format in some detail, though an output schema would help. Lacks error handling or edge case descriptions, but overall is complete.

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

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

Schema coverage is 100% with a description for the claim parameter. The tool description adds value by explaining supported claim types and return format, going beyond the schema's brief 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 uses multiple specific verbs (fact-check, verify, validate, confirm/refute) and clearly identifies the resource (natural-language factual claim). It distinguishes from siblings by emphasizing its specialized fact-checking role and efficiency (replacing 4-6 sequential calls).

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 (checking truth of user statements) and gives example queries. It also specifies the current scope (company-financial claims for US public companies), but does not explicitly state when not to use or mention alternative tools.

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