Last Fm

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns per-model scores, confidence, signals, raw response, and a combined view. It also notes that the API key is passed straight through. 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 concise (4 sentences) and well-structured, with the core purpose front-loaded. Every sentence adds value, and there is no redundant or unnecessary text.

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 adequately explains the return structure (per-model fields and combined view). It covers use cases, parameters, and cost implications for Anthropic. Could be slightly more explicit about error handling or edge cases.

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 context: default model is Workers AI, _apiKey enables Anthropic calls, and context helps disambiguate. This adds meaningful semantic value 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 uses specific verbs ('Probe', 'score') and clearly defines the resource (LLMs for entity visibility). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by specifying multi-model probing and a 0-100 visibility score.

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: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains the default model and optional Anthropic probing with BYO key. However, it doesn't explicitly contrast with similar tools like 'scan_competitor_ai_presence'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by specifying the external data source (Last.fm) and the exact data returned. No contradictions with annotations.

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

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

The description is a single, information-dense sentence that covers all essential aspects: action, source, input, output. No superfluous 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 annotations (readOnlyHint, openWorldHint, idempotentHint) and an output schema (not shown but present), the description provides sufficient context for a simple lookup tool. It does not mention pagination or limitations, but for album metadata this is acceptable.

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

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

With 0% schema description coverage, the description must compensate. It clarifies that the mbid parameter is an alternative to the artist+album pair, and provides examples in the schema. This adds meaning beyond the bare schema, though individual parameter details could be richer.

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

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

The description clearly specifies the action (fetching album metadata), the source (Last.fm), the required identifiers (artist and album name or MusicBrainz ID), and the returned data (track listing, counts, wiki, tags). It distinguishes itself from sibling tools like artist_info and track_info which target different 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 when to use the tool (when album metadata is needed) but does not explicitly state when not to use it. However, the context from sibling tool names provides differentiation, and the description is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description consistently describes a fetch operation. It adds valuable context about the returned data fields and language option, which goes 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 that concisely covers the tool's purpose, inputs, and outputs without redundancy or fluff. Every phrase adds value.

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

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

An output schema exists (not shown but indicated), so the description does not need to detail return formats. It mentions the main data fields (biography, counts, similar artists, tags) which matches typical expectations. Minor omissions like error conditions or rate limits are acceptable given the tool's simplicity and existing 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?

With 0% schema description coverage, the description must compensate. It clarifies that 'artist' can be a name or MBID and that 'lang' is optional. However, it does not explain the relationship between 'artist' and 'mbid' parameters (e.g., whether they are mutually exclusive or which takes precedence), leaving some ambiguity.

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

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

The description clearly states the tool fetches a Last.fm artist profile with specific data fields (biography, listener/play counts, similar artists, genre tags) and mentions alternative identifiers (name or MusicBrainz ID). It distinguishes the tool's comprehensive profile from siblings like artist_similar but does not explicitly contrast with them, so it's clear but not perfectly differentiated.

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

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

The description implies usage for fetching full artist profiles with optional language but provides no explicit when-to-use or when-not-to-use guidance relative to sibling tools. There is no statement about prerequisites or alternatives, leaving the agent to infer 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?

Description adds no behavioral context beyond annotations. With readOnlyHint and idempotentHint already set, the description misses opportunity to explain response structure or behavior like pagination or result format.

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?

Extremely short but under-specified. Conciseness is not achieved when meaningful information is omitted. The description should earn its place; this one provides minimal 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 low complexity (3 params, output schema exists), the description fails to cover basic usage context. Leaves agent without understanding of return values or parameter relationships.

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%. Description 'Similar artists.' provides no explanation of parameters (artist, mbid, limit). Does not compensate for the lack of 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 'Similar artists.' is vague and lacks a specific verb. It restates the name without specifying what the tool does (e.g., retrieve, list, find). Fails to differentiate from sibling tools like artist_info or artist_top_tracks.

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. Siblings include artist_info, artist_top_tracks, and chart_top_artists, but no context provided for 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. But the description adds nothing beyond 'most-played tracks'—no details on data freshness, return format, or pagination.

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?

Extremely short (5 words), which is under-specification rather than conciseness. Front-loading is fine, but lacks structure and substantive 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?

Despite having an output schema, the description does not hint at what the tool returns (e.g., a list of tracks). For three parameters and a non-trivial output, the description is incomplete for an agent to understand behavior.

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

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

Schema description coverage is 0%, so description must explain parameters. It does not clarify mbid (likely MusicBrainz ID), limit, or the purpose of artist beyond its property name. No added value over 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 clearly states the tool returns most-played tracks for an artist, which is a specific verb-resource combination. It distinguishes from siblings like 'track_info' and 'artist_info'. However, it lacks nuance on what defines 'top' (e.g., play count or popularity).

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 vs alternatives like 'track_search' or 'user_top_tracks'. No mention of when not to use or prerequisites.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses several behavioral traits: it routes to a large tool corpus, fills arguments automatically, returns structured data with stable pipeworx:// citation URIs, and is described as 'one fast call'. It also implies this tool may be less hallucination-resistant than ask_pipeworx_grounded, which is valuable behavioral context.

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

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

The description is long but well-structured, with a strong opening directive ('PREFER OVER WEB SEARCH'), concrete examples, and clear transitions to alternatives. Every sentence adds value, but the length is slightly dense for an agent to parse quickly, hence not a perfect 5.

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

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

The description covers all essential context: what it does, when to use it, what it returns, and how it differs from alternatives. It includes multiple examples and addresses special cases like breaking news. With no output schema, the description provides sufficient details for an agent to select 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?

The input schema already fully documents the 'question' parameter and its aliases (q, text, input, query, prompt) with 100% coverage. The description adds no additional parameter-specific details, only general usage examples. This meets the baseline for high schema coverage but does not go beyond 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 that the tool routes questions to the right one of 5,529 tools across 1,455 verified sources, fills arguments, and returns structured answers with citation URIs. It also explicitly says 'START HERE for most questions' and distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides extensive usage guidance: 'PREFER OVER WEB SEARCH' for specific categories, 'Use whenever the user asks...' with example phrases, and explicitly names alternatives ('step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for a broad question use deep_research'). This gives clear when-to-use and when-not-to-use 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: it is experimental, may have routing improvements enabled live, currently matches ask_pipeworx exactly, and its results are used for comparison. It also states 'this IS a full working router', preventing misconceptions about limited functionality.

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 convey a lot of information, but the exact count '5,529' and the date '2026-07-26' add specificity. The description is slightly verbose but well-structured and front-loaded with the core purpose.

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

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

The description is comprehensive given the tool's complexity: it defines the routing behavior, experimental status, relationship to the stable version, and fallback semantics. Without an output schema, it does not detail response format, but 'same response shape' adequately references the sibling tool for that.

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 parameter and five aliases fully documented. The description only mentions 'same arguments' without adding detail, but the schema already provides all necessary parameter semantics. 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 the tool is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. The verb 'ask' and resource 'pipeworx' are implicit, but the explanation of it being a full working router with experimental routing improvements makes the purpose unambiguous.

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

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

Explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router. It also clarifies that it is not a fallback ('Falls back to nothing') and that results are compared against the stable router, giving clear when-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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses behavioral traits: it makes an extra LLM call, extracts answers using only tool result content, and returns structured refusal reasons on failure. It also specifies the exact success and refusal response shapes, which is especially valuable given the lack of an output schema.

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 information-dense but well-structured: mechanism, return format, use cases, and tradeoff are each covered in distinct sentences. No fluff or redundant repetition of schema or annotation details. Every 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?

Given the moderate tool complexity and absence of an output schema, the description fully compensates by detailing the success/refusal response objects, the routing mechanism, the cost tradeoff, and concrete use cases (financial, legal, medical). The agent has enough context to select and invoke the tool correctly, and to interpret its result.

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

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

The input schema already provides 100% coverage for all six parameters (all aliases for 'question'). The description does not add parameter-specific syntax or format details beyond what the schema states, but it does imply via usage context that the question should be natural-language and read-oriented. This meets the baseline for high schema coverage without adding much extra semantic 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 this is a 'hallucination-resistant answer mode' for high-stakes reads, distinguishing it from the sibling tool ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior. The verb+resource is specific and the scope (extracting answers with evidence) is unambiguous.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). Also names the alternative (ask_pipeworx) and provides a cost tradeoff, giving clear decision 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 indicate readOnlyHint=true, idempotentHint=true. Description adds extensive behavioral details: market resolution, classification, fan-out, evidence packet structure, resolver contract, safety short-circuits, closed market handling, spread warnings, resolution-rule risk. Goes well 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?

Description is long but well-structured, front-loaded with purpose and usage. Some examples are verbose but justified given complexity. Could trim fan-out examples 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?

Covers all aspects: input variations, fan-out behavior, response shapes, resolver contract, parent event extraction, news fields, safety, illiquid markets, resolution-rule risk. No output schema, but description compensates thoroughly.

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

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

Schema coverage 100%. Description adds significant meaning: market parameter explained with examples (slug, URL, question text); depth parameter explained with behavior (quick vs thorough); include_raw parameter explained with trade-off (summarized vs full payloads).

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 verb 'research', resource 'Polymarket bet', and action 'pulling relevant Pipeworx data'. Distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on a single bet.

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 usage scenarios ('should I bet on X', 'what does the data say about Y') and describes safety and resolution issues. Could be more explicit about when not to use, 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 read-only, open-world, idempotent, non-destructive. The description adds behavioral context: returns ranked artist names with listener and play counts, and notes keyless access. 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-load the core purpose and immediately provide usage guidance and exclusions. No filler.

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

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

For a single-parameter read-only tool with output schema, the description covers purpose, usage, and output format. Minor gap is limit parameter semantics, but that is already handled in parameter dimension.

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

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

The schema has only 'limit' with no description (0% coverage). The description does not mention the limit parameter, its default, or allowed values, leaving the agent to infer its semantics solely from the property name and example.

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

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

The description clearly states the tool provides global top artists by listener count, using 'world's most-popular music right now' and explicitly contrasts with tag_top_artists for genre and user_* tools for named user histories. This distinguishes it from siblings.

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

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

Explicit PREFER list with example queries and exclusions for genre and user-specific cases. Also notes keyless operation, which helps the agent know there are no auth prerequisites.

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 meaningful behavioral details: results sorted by primary metric, correct handling of off-calendar fiscal years, and inclusion of citation URIs. 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?

Description is relatively long but well-organized with examples and bullet points. Every sentence adds value, though slight tightening could improve conciseness.

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 thoroughly explains what is returned (paired data, citation URIs, sorted results) and covers both entity types. It also notes efficiency gains over sequential lookups, making the tool's value clear.

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 adds significant meaning beyond schema: explains what each value of 'type' pulls (company financials vs. drug stats), and clarifies that 'values' are tickers/CIKs or drug names. This greatly aids correct 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?

Description clearly states it performs side-by-side comparison of 2-5 companies or drugs. It lists specific use cases (e.g., 'which is bigger', 'rank these companies') and distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

Explicitly encourages preference over sequential lookups when comparing entities, and provides example queries. However, it does not explicitly state when not to use (e.g., for single entity queries), though this is implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond these: account/payment requirements, parallel tool routing, explicit gaps[] to avoid hallucination, contradictions[] for standard/thorough, citation_uri fetchability, semantic excerpting, and expected latency. It does not contradict any annotation.

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

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

The description is dense and every sentence conveys a meaningful constraint or capability (account requirement, alternative tools, output structure, latency, etc.). It is front-loaded with the most critical operational note (account required). However, it reads as a long block of text, and while not bloated, it could be structured into shorter paragraphs or bullets for easier 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?

Despite having no output schema, the description fully specifies what the tool returns: 'findings packet: verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding, with explicit gaps[].' It also covers response fields like `hop` and `citation_uri`, contradiction detection, and timeout expectations. For a complex research tool, this is a complete operational picture.

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 both 'question' and 'depth' fully described. The description adds extra nuance for depth values—e.g., 'standard' re-angles unanswered gaps and 'thorough' chases leads—and clarifies that broad multi-part questions are acceptable, which goes beyond the schema's basic 'natural language' hint. This additional context pushes it above the baseline of 3.

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

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

The description clearly states a specific verb-resource relationship: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explains the decomposition mechanism, parallel routing, and output packet, and explicitly distinguishes from open-web search and sibling tools like ask_pipeworx. This leaves no ambiguity about what the tool does.

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

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

Explicit guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also explains when to use each depth level (quick/standard/thorough) and the gap-recovery behavior, giving clear when-to-use and when-not-to-use 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds that the tool is non-destructive and returns results 'ready to call directly, no second schema lookup needed.' No contradictions; the description enriches the behavioral profile 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 well-structured: it starts with a clear verb phrase, lists use cases concretely, explains the output format, and ends with usage advice. 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?

Despite no output schema, the description explicitly states what is returned (names, descriptions, schemas with examples) and that results are callable directly. Given the tool's discovery purpose and the context of many sibling tools, this description is fully 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% with descriptions for each parameter, including aliases. The description adds value by providing examples of natural language queries and clarifying that 'query' accepts free-form descriptions. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing data/task, lists specific domains (SEC filings, financials, etc.), and explains it returns top-N relevant tools with names, descriptions, and schemas. This distinguishes it from sibling tools, which are specific tools rather than a discovery 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 says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also specifies when to use (browse, search, look up, discover) and implies when not to (if you already know the tool). This provides strong guidance on usage 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 declare readOnly, idempotent, openWorld. Description adds context on parallel fan-out across SEC, XBRL, USPTO (with sunset caveat), GDELT, GLEIF, and specific return fields. This transparency about sources and limitations goes beyond annotations. However, it doesn't describe pagination or rate limits, which might be relevant but not critical.

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 example queries and a clear statement of purpose. It includes detailed information on sources, return fields, and limitations. While comprehensive, it is somewhat lengthy but remains well-structured and informative. A slightly more compact version could improve conciseness.

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 thoroughly explains what the tool returns, including specific data fields, source breakdowns, and a known limitation (patents sunset). It covers input constraints, usage preference, and fallback options. This is complete for an AI agent to understand tool behavior.

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

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

Input schema already provides detailed descriptions for both parameters, including examples and constraints. The description reiterates these points but does not add significant new semantic information beyond the schema. Therefore, score at baseline for high coverage.

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

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

Clearly states it provides a holistic cross-source profile for US public companies. Distinguishes itself from chaining multiple individual lookups and mentions resolve_entity for name resolution. The description is specific and actionable.

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 the tool should be preferred for holistic queries over chaining single-source tools. Also provides clear input constraints (ticker or CIK, not names) and directs to resolve_entity for names. Includes caveat about patents sunset.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds limited extra behavioral context. The description mentions clearing sensitive data, which provides some additional insight but is not highly detailed.

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

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

Two sentences, front-loaded with the action and resource, no extraneous information. Every sentence serves a 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and pairing with related tools. It is fully 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% with a clear description for the 'key' parameter. The description only says 'by key', adding minimal meaning beyond the schema's 'Memory key to delete'.

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 'Delete a previously stored memory by key', specifying the verb and resource. It also mentions the sibling tools 'remember' and 'recall', distinguishing the tool's purpose from those.

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, the task is done, or you want to clear sensitive data'. It pairs with 'remember' and 'recall' but does not explicitly state when not to use this tool or provide alternatives beyond the pairing.

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, idempotent, non-destructive, openWorld. The description reinforces these by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', adding behavioral detail 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 with no fluff. The first sentence states the core action, the second explains the process, the third lists use cases. Every sentence adds value and the structure is front-loaded.

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

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

Given the annotations (readOnlyHint, idempotentHint, etc.) and 100% schema coverage, the description provides sufficient context. It mentions the output format ('single text blob') and use cases. No output schema is needed.

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

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

Both parameters (url, max_links) are fully described in the schema (100% coverage). The description adds context for url ('Fetches the page') but does not enhance max_links beyond the schema defaults. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the action (generate), resource (llms.txt from a URL), and the expected output format. No sibling tool overlaps with this functionality.

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: getting a client's site indexed, drafting for own project, auditing competitors. It provides clear context for when to use, though it does not 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?

Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds value by enumerating the returned fields (id, type, params, etc.) and specifying that only active subscriptions are returned by default, which is useful 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?

Two concise sentences: first describes purpose and output, second provides usage guidance. No wasted words, information is front-loaded and easy to parse.

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 low complexity (one optional parameter, no output schema needed), the description fully covers what the tool does, what it returns, and when to use it. 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% with a clear description of the 'include_inactive' parameter. The description does not need to add more, as the schema alone suffices. Baseline score 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 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by being the listing counterpart.

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 usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool and implicitly when not to (no need to search manually).

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

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

Annotations provide only false flags, so the description carries the burden. It discloses return behavior (claim_token for anonymous submissions), rate limit (5 per identifier per day), cost/quota (free, doesn't count), and process (digest read daily, affects roadmap). It also warns against pasting user prompts, which is useful operational behavior.

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

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

The description is long but thoroughly front-loaded with a clear purpose and then structured use cases. Every sentence serves a distinct function: scope, categories, exclusion criteria, token workflow, rate limits, and free cost. No filler; the density is justified by complexity.

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

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

Given the tool's complexity (multiple feedback types, optional account and token, rate limiting), the description covers scope, exclusions, usage, token behavior, rate limits, and cost. It also directs the agent on how to frame the message. Even without an output schema, the agent has enough context to invoke it correctly in all relevant cases.

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

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

The input schema already covers all parameters with detailed explanations (100% coverage), which gives a baseline of 3. The description adds meaningful guidance beyond the schema, such as the claim_token flow ('pass it back later... to read whether it was fixed') and message content ('describe in terms of Pipeworx tools/packs – don't paste the end-user's prompt'), enhancing the meaning for these parameters.

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+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes from siblings by limiting scope to Pipeworx tools and listing specific categories (bug, feature/data_gap, praise), so an agent can accurately select this over 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 provides when-to-use conditions ('Use when a tool returns wrong/stale data...') and when-not-to-use ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). This is unambiguous and grounded in the detailed 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, etc.) are already strong. The description adds useful context: data source (CF analytics-engine), privacy (no PII), and caching policy (5min-1h). 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?

Description is concise (4 sentences) and front-loaded with the main return. Each sentence adds value. Minor redundancy with schema description could be trimmed, but overall 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 no output schema, the description adequately explains return content and data characteristics. It also covers caching and source. Could mention result sorting or count limits, but sufficient 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?

Schema coverage is 100% for the single parameter 'window', with a clear description of enum values and their implications. The tool description reinforces this but does not add significant new meaning beyond what the 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?

The description clearly states the tool returns top tools, top packs, and total call volume over a configurable window. It distinguishes itself from sibling tools like discover_tools or ask_pipeworx by focusing on aggregated trending data from AI agent 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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical tools, assessing use case alignment). While not stating when not to use, the hints about self-aggregation and curation provide 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. Description goes far beyond by detailing algorithm (monotonicity, partition checks), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), and fill check against CLOB depth. All behavioral traits disclosed 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?

The description is long but well-structured with bold labels and logical flow. It front-loads the purpose and layers details. Every section adds value, though the fill check and response format details could be slightly trimmed for brevity. Still, given complexity, the length is justified.

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

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

Given two optional parameters, no output schema, and rich annotations, the description is fully complete. It covers all modes, parameters, response fields (opportunities[], partition_check), fill check criteria, and references a sibling tool. No gaps for an agent to select or 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?

Both parameters (event, topic) have 100% schema coverage, but the description adds rich context: event mode explains slug usage and market walking; topic mode explains cross-event scanning and token similarity. This goes well beyond the schema descriptions, adding significant value for correct invocation.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb, resource, and method, and distinguishes between three modes (trending_scan, event, topic), differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' Recommends event mode for a specific market, explains when not to trade (if realizable_edge_pp <= 0), and directs to 'polymarket_fill_risk' for custom sizing. No ambiguity.

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

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

The description discloses behavioral traits beyond annotations, including caching ('Cached 1h at the KV level'), response structure (by_segment, diagnostics), and edge calculation details (slippage, Kelly fractions). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, 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?

The description is well-structured and front-loaded with the core purpose, but it is verbose with detailed explanations of model families and edge calculation. Every sentence adds value, though some could be condensed.

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

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

Given the tool's complexity (9 parameters, no output schema, nested output structure), the description is comprehensive. It explains the response structure, filtering logic, edge calculation, caching, and diagnostics. It provides enough detail for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the purpose of each knob (e.g., min_kelly skips small opportunities, min_partition_leg_kelly applies to partition arbs). The description clarifies how parameters interact with the edge logic and response 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 verb 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the use case 'what should I bet on today' and distinguishes from sibling tools by focusing on edge discovery without paging hundreds of markets.

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 ('agents discover opportunities without paging hundreds of markets') and provides guidance on filtering via knobs like min_liquidity and max_spread_pp. It also notes excluded categories (Fed bets) and why. However, it does not directly compare with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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. The description adds key behavioral traits: uses snapshots, computes trends (new, widening, stable, decaying), includes expired opportunities, and explains data gaps. 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 fairly long but well-structured: purpose, output fields, limits. Every sentence adds value. However, it could be slightly more concise without losing 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?

No output schema, so description covers all return fields: tracked[], expired[], snapshot_dates[] with detailed explanations. It also includes limits and edge cases. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so parameters are documented. The description adds meaning: days default 14, clamp 2-30; window options '24hr | 1wk | 1mo' and default. It also explains how they affect output (snapshots, response structure).

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It specifies the resource (polymarket_edges snapshots) and the verb (answers), distinguishing it from sibling tools like polymarket_edges.

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

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

The description provides context for when to use the tool, explaining the difference between a fresh edge and an old one. It also notes limits (60-day TTL, snapshot start). However, it does not explicitly list when not to use or compare with siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context: it walks the ladder, returns specific fields, and warns about forced directional risk. It does not contradict annotations. A 4 because it adds non-trivial behavioral detail beyond what annotations convey.

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

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

The description is well-structured, starting with purpose, then requirements, then detailed explanations for both modes, return fields, and usage guidelines. Every sentence earns its place; 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 no output schema, the description fully explains all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket). It also covers edge cases like partial fills and directional risk.

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 significant meaning: explains default for side in basket mode (auto from partition sum), interprets size_usd differently for basket (settlement notional), and clarifies the distinction between single-market and basket modes. 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from siblings by specifying it is a risk check to be used before acting on arb signals, not an execution or edge calculation tool.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position. Provides clear context and alternatives.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds extensive behavioral details: compatibility_warning conditions, temporal alignment flags, skipped counter explanations, and the fact that real spreads require equivalent bet shapes. No contradiction with annotations.

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

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

The description is fairly lengthy but well-structured: it starts with the core purpose, then details modes, response fields, safety fields, and caveats. Every sentence adds value, though some redundancy exists (e.g., repeating 'pre-mapped ≠ tradeable'). It is front-loaded with the primary 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?

Without an output schema, the description fully explains the response structure: leg-by-leg prices, spread array with top_spreads_pp, compatibility_warning, temporal_alignment, and various counters. It covers all key aspects needed to use and interpret the tool, including edge cases like unmatched events.

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% (all three parameters described). The description adds meaning beyond schema by explaining the two modes (topic vs explicit), how they interact (explicit overrides topic), listing all topic shortcuts, and providing examples. This helps the agent understand parameter relationships.

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 the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage (likely intra-venue) and others. Verb+resource (compute/check spread) is specific and accurate.

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 (to compare prices across venues) and when not to (when compatibility_warning fires, indicating non-equivalent bet shapes or unrelated events). It provides guidance on the two modes and warns that most pre-mapped topics are not tradeable, effectively telling users to interpret results cautiously.

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, indicating safe read. Description adds scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, providing additional 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?

Three sentences, front-loaded with the core action. Every sentence serves a purpose: define action, give usage context, and mention scoping/pairing. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and relation to sibling tools. Nothing essential is missing.

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

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

The single parameter 'key' is fully described: omit to list all keys or provide a key to retrieve a specific value. Schema coverage is 100%, and the description adds practical usage guidance beyond the schema's type definition.

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

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

Clearly states the tool retrieves a previously saved value or lists all keys, with examples of use cases (ticker, address, notes). Distinguishes from siblings by mentioning pairing with 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 explicit context for when to use (look up stored context without re-deriving) and includes examples. Lacks explicit 'when not to use' or alternatives, but the context is sufficient for an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: the mark_read parameter modifies state by flagging events as read, affecting future calls. It also explains the feed is persisted and accessible elsewhere, 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 concise with two sentences: the first covers core functionality and return structure, the second details filters and mark_read behavior. It ends with a useful note about alternative access. Every sentence adds value with no redundancy.

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

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

Given the absence of an output schema, the description adequately explains return fields (source, citation_uri, raw payload) and filtering options. It covers parameters and state behavior. Missing explicit ordering or pagination details, but overall complete for a simple read tool with 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% with all 5 parameters described. The description adds meaning beyond the schema: it specifies ISO timestamp format for 'since', explains the effect of mark_read, and gives an example filter type ('sec_8k'). This compensates for the schema's minimal 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 pulls fired events from a subscription feed, returning recent alerts with specific fields like source and citation_uri. It distinguishes itself from sibling tools focused on subscriptions (list_subscriptions, subscribe, unsubscribe) by emphasizing real-time alert retrieval.

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

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

The description provides clear context for use: retrieving recent alerts with optional filters for type, time, and read status. It mentions polling works fine and offers an alternative GET endpoint for scripts/dashboards, but does not explicitly exclude other tools or specify 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?

Discloses fallback mechanism (GDELT→GNews), USPTO soft-fail, return format, and parameter details. Annotations confirm readOnly, openWorld, idempotent, non-destructive; no contradiction.

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

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

Well front-loaded with examples, but a single paragraph with multiple ideas. Could be slightly more structured, but remains concise.

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

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

With no output schema, description adequately explains the return structure (changes grouped by source, total_changes, URIs) and limitations (only company, USPTO soft-fail).

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%. Description adds value by explaining since formats (ISO vs relative) with examples, and clarifies value accepts 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?

Clearly states it returns a change feed for a company, lists sources (SEC, GDELT/GNews, USPTO), and gives example queries. Distinguishes from sibling 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?

Explicitly gives query examples and directs when to use entity_profile instead for static profiles. Provides guidance on since parameter values like '30d' for typical monitoring.

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 storage as key-value pair scoped by identifier, and persistence differences between authenticated and anonymous sessions. These details add value beyond annotations (readOnlyHint, destructiveHint, idempotentHint) and 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?

Concise, front-loaded with purpose, and every sentence adds value (purpose, usage guidance, behavioral detail). No redundancy.

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

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

Covers purpose, usage, and behavioral traits well. Minor gap: does not mention what the tool returns (e.g., success confirmation), but annotations help fill idempotent behavior.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add significant extra meaning beyond what the schema already provides, warranting a baseline score.

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 'save' and resource 'data', and distinguishes its purpose from sibling tools like 'recall' and 'forget' by positioning it as the storage operation.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and mentions complementary tools ('recall' and 'forget'). Lacks explicit exclusions or when-not-to-use, 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses important behavioral traits: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), the handling of unresolved identifiers ('stated explicitly under `unresolved` rather than omitted'), and internal cascading lookups. This is rich, useful context.

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

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

The description is longer than average but well-organized: example queries, a core statement, SUPPORTED TYPES with nested details, and a note on internal efficiency. It is front-loaded and every section earns its place; the only minor issue is the density of parenthetical detail in the 'company' section.

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?

There is no output schema, so the description compensates by explaining what is returned (identifiers labelled with source, unresolved field) and edge-case behavior (graceful degradation). The complexity of two entity types with multiple identifiers is well covered, making the description complete 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful nuance: it explains the 'company' type accepts ticker, CIK, or name; the 'drug' type accepts brand or generic; and it specifies the output domains (CIK/LEI/FIGI from specific sources). This goes beyond a simple parameter listing.

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

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

The description opens with concrete query patterns ('What's the ticker for...', 'find the CIK for...') then states the verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly distinguishes it from sibling tools like entity_profile or track_search, which 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 gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups, giving context on when to prefer it. It does not explicitly name alternative tools or state when not to use it, but the instruction is strong enough for a 4.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and outputs a ranked list with score, confidence, signal density. It also specifies first entity treated as 'subject' for narrative. No contradictions with annotations.

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

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

The description is a single paragraph with clear structure: purpose, mechanism, use case, output. Every sentence adds value. No redundant information. Front-loaded with the core action.

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

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

The description covers what, how, and output format (ranked list with score, confidence, signal density). Though no output schema, the description provides sufficient detail for an agent to understand the return type. Slightly lacking in exact structure, but adequate given 4 parameters and no nested objects.

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% (all 4 parameters described). The description adds meaning beyond schema: limits entities to 2-8, clarifies first is subject, states default model is workers-ai and _apiKey needed for anthropic. These details compensate for schema's lack of constraints.

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

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

The description explicitly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It provides a concrete use case ('does Claude know about us as well as our competitors?') and clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic compare).

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

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

The description clearly indicates when to use: for competitive AI-marketing audits. It implies not to use when only one entity is needed (since it probes multiple). However, it does not explicitly state exclusions or alternatives beyond the implied contrast with ai_visibility_check.

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

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

Description adds significant context beyond annotations: details partial failures, timing (bundlephobia first measurement 5-30s), graceful degradation (sources_failed list), and that it fans out to two services. 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?

Description is somewhat long but every sentence adds value; it is front-loaded with the composite nature. Could be slightly more terse, but overall 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?

Even without an output schema, the description details the return structure (summary block, per-advisory detail, links, alternative versions, sources_failed). It is complete for a scanning tool with partial failure handling.

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 adds extra meaning: package accepts scoped packages, version defaults to latest. This goes beyond the schema descriptions.

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

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

The description clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs ('scan') and resource ('dependency'), and distinguishes itself from sibling tools by specifying the ecosystem (NPM only).

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 an agent asks about safety, popularity, size, or cost of adding an npm package. Also provides when not to use: NPM ecosystem only in v1, with alternatives mentioned for other ecosystems (PyPI, Maven, etc.).

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

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

Beyond the annotations (readOnlyHint, etc.), the description reveals embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character limit (200K chars with truncation and flagging), and that each passage carries an offset for verification. This is rich behavioral context.

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

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

The description is comprised of two well-structured sentences. The first defines the core functionality, and the second provides usage guidance and technical details. Every sentence is informative and there is 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?

The description explains the return format (passages with offsets and scores), truncation behavior, and the tool's role in a multi-step workflow. Given there is no output schema, this is sufficient for an agent to understand inputs, outputs, and boundary conditions. It fully covers the tool's complexity.

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

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

Schema coverage is 100% with descriptions provided for all three parameters. The description adds value by reinforcing constraints (e.g., 'max ~200K chars' for 'text'), providing default values ('limit' default 5), and giving natural-language examples for 'query' (e.g., 'supply-chain risk'). This enhances the schema beyond 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 the tool performs semantic search inside a given text, returning relevant passages with offsets and scores. It distinguishes itself from siblings by explicitly mentioning 'ask_pipeworx_grounded' as a complementary tool and highlighting the benefit of saving 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?

The description provides explicit guidance on when to use the tool: 'Use when the record is too big to cram into the prompt.' It also explains the integration pattern with 'ask_pipeworx_grounded', detailing how to fetch and then ground over relevant passages. No alternative tools are listed, but the pairing 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?

Adds context beyond annotations: returns id, requires OAuth, details on type-specific behavior, delivery channel limitations (SMS cap, webhook auto-disable). Slightly unclear on idempotency 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?

Single paragraph with front-loaded purpose. Every sentence adds value, though could be formatted for easier 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?

Covers purpose, requirements, types, delivery details, constraints. Lacks error scenarios and explicit idempotency explanation, but sufficient given schema coverage.

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?

Provides detailed examples and clarifications for each type in params and delivery, adding significant value beyond schema descriptions. No 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?

States clearly it creates a subscription and returns an id. Distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts by focusing on creation.

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 requires Pipeworx OAuth account, excluding anonymous/BYO users. Lists supported types and delivery constraints, 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it returns examples with exact tool+argument shape and is the onboarding entry point, going beyond annotations without contradicting them.

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

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

The description is long but well-structured, starting with common user phrases, then the core purpose, usage instructions, and parameter details. Every sentence adds value, though slightly verbose.

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

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

With no output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shape). Parameter is thoroughly covered, and the usage context is complete for an onboarding tool.

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

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

Schema already describes 'topic' with 100% coverage; description adds specific example values (finance, pharma, etc.) and clarifies that omitting gives a full spread. This enriches the schema 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 category-bucketed example questions for an agent onboarding. It specifies the verb 'returns' and the resource 'example questions', and distinguishes it from siblings like 'ask_pipeworx' by being the entry point for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains when to pass 'topic' vs omit it, providing clear when/why 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, idempotentHint=true, destructiveHint=false. Description adds that the tool returns ranked artist names with listener counts. No contradiction, but no additional behavioral detail (rate limits, pagination) 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?

Single sentence that front-loads the verb and resource. Every word adds value. No redundancy. Highly concise.

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 output schema present and annotations covering safety, the description is adequate but lacks parameter details. The tool is simple (2 params), so minimal description is acceptable, but parameter semantics are missing.

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

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

Schema description coverage is 0%, so description must compensate. It mentions tag is a genre tag and gives examples, but does not explain valid values or the limit parameter. No additional semantic meaning beyond implicit examples.

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

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

Description clearly states the action (Fetch), resource (top Last.fm artists), and qualification (for a genre tag). Examples given. Does not explicitly differentiate from siblings like chart_top_artists, but the genre-specific context makes it distinct.

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 explicit when-to-use or when-not-to-use guidance. Siblings exist (e.g., chart_top_artists, artist_info) but no differentiation or context provided. Agent must infer usage solely from the general purpose.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds detail about data source (Last.fm) and returned fields, which is helpful. No contradictions or missing critical 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?

Single sentence that is front-loaded with purpose and comprehensively lists key outputs. 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 the tool's simplicity, description covers purpose, parameters, and return types. Output schema provides structure for return values, but description already lists all relevant fields. Complete 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 0%, so description must compensate. It mentions 'artist and track name (or MusicBrainz ID)' but does not explain the mbid parameter format, optionality, or how it relates to artist/track. The schema shows mbid as optional but description implies it's an alternative; more clarity needed.

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 'Fetch', resource 'Last.fm track metadata', and key outputs (duration, counts, tags, summary). It distinguishes from sibling tools like 'track_search' and 'album_info' by specifying exact lookup by artist/track name or MusicBrainz ID.

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 explains when to use (when you have artist and track name or MBID) but does not explicitly state when not to use or compare with alternatives like 'track_search'. However, the specificity is strong enough for an agent to infer 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 already declare it as read-only, idempotent, and non-destructive. The description adds that results are ranked and include artist, track name, and listener counts, which goes beyond the structured annotations. However, it does not disclose any additional behavioral aspects like authentication 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 immediately conveys the tool's purpose, source, action, and result format. No extraneous information; every word adds value.

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

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

Given the tool's simplicity (2 parameters, output schema present, rich annotations), the description covers the main purpose and result structure. However, it omits explanation of the 'limit' parameter, which is a notable gap for a complete understanding. The output schema covers return values, so return format is sufficiently documented.

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 coverage, the description should explain both parameters. It only implicitly explains 'query' as a 'keyword query' but says nothing about 'limit' (e.g., max results, default value). The description focuses on output rather than input, leaving one parameter undocumented.

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

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

The description clearly states the tool searches Last.fm for tracks by keyword query and returns ranked results with specific fields (artist, track name, listener counts). It distinguishes this from sibling tools like track_info (which likely returns detail for a specific track) and artist_top_tracks (which is artist-specific).

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

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

The description implies usage when a keyword-based track search is needed, contrasting with more specific lookup tools. It does not explicitly state when not to use, but the context of sibling tools and the clear purpose provide adequate 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 ownership enforcement and row deactivation detail beyond annotations. Annotations already indicate idempotent and non-destructive, description complements.

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, no wasted words, front-loaded with 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?

Covers purpose, ownership, effect on data, and historical availability. Adequate for a simple mutation tool with one parameter.

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?

Single parameter 'id' with schema coverage 100%. Description adds that it's a uuid from subscribe, but schema already provides similar info. Baseline score 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 verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling tools like subscribe and list_subscriptions.

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?

Explains ownership enforcement and behavioral details (deactivation, not deletion). Lacks explicit when-not-to-use or alternative tool references.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by stating it 'Returns track names, artists, and play counts' and by reinforcing the constraint against guessed usernames. It doesn't mention rate limits or error handling, but for a simple read operation with strong annotation coverage, the additional context is sufficient.

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 long sentence followed by a short second sentence. It's dense but every clause adds value: the scope, period values, usage restrictions, and return contents are all packed in without fluff. It's slightly verbose but not to the point of being bloated.

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

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

The tool has only three parameters with one required, and an output schema exists, so the description needn't explain return structure in depth. The description covers the main scenarios, restrictions, and period options. It's complete for an agent to decide when to use it and what to expect.

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

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

The schema only describes the 'user' parameter, so coverage is low. The description compensates by explicitly listing the accepted period values (overall/7day/1month/3month/6month/12month) and clarifying that 'user' must come from the caller, not be guessed. The 'limit' parameter isn't described, but it's a standard concept and the description's partial compensation keeps this from being a major gap.

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 the specific verb 'Fetch' and names the exact resource: 'a SPECIFIC NAMED Last.fm user's most-scrobbled tracks'. It also distinguishes itself from siblings by explicitly stating 'only when the question names a Last.fm username' and contrasting with chart_top_artists and tag_top_artists.

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 criteria ('only when the question names a Last.fm username') and clear exclusions ('NEVER for general popular songs / top music questions'), even naming the alternative tools to use instead. It also warns against using guessed or example usernames.

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 well beyond the readOnly/openWorld/idempotent annotations by explaining the meaning of each verdict, especially the critical distinction between 'could_not_verify' (did not happen, with error details) and 'unsupported' (no source). It also discloses the use of citations and the overall evidence pipeline, which is valuable behavioral context not present in the annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the trigger phrases, then logically explains the two processing paths, the return structure, and the critical caveats for callers. No unnecessary fluff; the length is justified by the tool's complexity.

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

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

Given the tool's complexity, no output schema, and no sibling differentiation, this description is remarkably complete. It explains the return values, edge cases, error semantics, and the fact that it replaces multiple sequential calls. It leaves no ambiguity about what the agent will receive or how to interpret the result.

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

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

The schema already provides 100% coverage of both parameters, and the description adds substantial extra semantics: it explains how tolerance_pct overrides the claim's implied tolerance, gives a range (0.5–50), recommends 1–2 for hallucination detection, and states the default behavior. The claim parameter is clarified with examples and the overall invocation pattern, exceeding what the 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?

The description clearly states the tool's purpose: natural-language claim verification/fact-checking, with specific verb phrases like 'fact check' and 'verify the claim that…'. It distinguishes the tool from siblings by emphasizing its automatic routing and single-call nature, which is not replicated in other tool descriptions.

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 whenever the agent needs to check whether something a user said is factually correct') and describes the internal dichotomy between company-financial and other claims. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools like compare_entities or deep_research, so it falls just short of full explicitness.

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