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?

Annotations declare readOnly, openWorld, and idempotent hints, and the description adds valuable context beyond those: it routes to an enormous internal tool ecosystem, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. This clearly describes operational behavior without contradicting annotations.

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

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

The description is longer than average but every section earns its place: scope, trigger phrases, examples, alternative routing, and caveats. There is slight redundancy ('PREFER OVER WEB SEARCH' and 'START HERE' both make the same point), but the front-loaded directive and clear structure keep it usable.

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 router with a single required natural-language parameter and no output schema, this description is complete. It tells the agent when to use it, what to expect (structured answer with citations), how it compares to siblings, and provides representative examples covering multiple domains.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description itself adds no additional parameter-level semantics, but the schema already fully covers what the agent needs to know, so the baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a router that sends factual questions to one of 5,743 tools across 1,500 sources and returns structured answers with citation URIs. It explicitly contrasts itself with web search and sibling tools like ask_pipeworx_grounded and deep_research, so an agent can distinguish them without opening schemas.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and lists concrete trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also names alternatives with their specific conditions: ask_pipeworx_grounded for hallucination-resistant single answers, and deep_research for broad/multi-part questions.

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 valuable context beyond the annotations by disclosing that this is a live experimental edge, that no candidate is currently active, and that behavior currently matches ask_pipeworx exactly. It also clarifies that the tool is a full working router rather than a fallback stub. It stops short of describing the response shape in detail, though it points to the stable sibling for that.

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 and information-dense, with each sentence contributing a distinct fact: beta status, identical surface, current inactive candidate, usage instruction, and fallback clarification. There is slight redundancy between 'identical' and 'currently matches exactly', but it is not 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?

For a single-required-parameter router, the description covers current behavior, relationship to the stable alternative, and safety context through annotations. The absence of an output schema is mitigated by stating that the response shape is identical to ask_pipeworx, which an agent can reference.

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

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

Schema coverage is 100%: the required question parameter is documented, and all five aliases explicitly map to it. The description adds no new parameter-level semantics, but none are needed because the schema already conveys that the only meaningful input is a natural-language question.

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

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

Clearly identifies the tool as the beta variant of ask_pipeworx, a universal router over 5,743 tools with the same arguments and response shape. It also differentiates itself from stable siblings by calling out experimental routing improvements and the current inactive candidate state.

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

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

Explicitly instructs the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router to inform merges. It does not explicitly list exclusion conditions like 'use stable for production', but the intended experimental 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?

While annotations already mark the tool as read-only, idempotent, and non-destructive, the description goes well beyond by disclosing exact refusal behavior with refusal_reason enum values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also reveals the evidence-quote extraction mechanism and the extra LLM call cost, which are not captured in annotations or schema. This is rich, actionable behavioral transparency with no contradiction.

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

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

The description is longer than average, but every sentence contributes: purpose, routing behavior, success/refusal shape, use cases, and cost tradeoff. It is front-loaded with the core purpose and structured with clear success/refusal blocks. Slightly tighter wording could make it even more concise, but it is dense and well-organized rather than padded.

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

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

For a tool with no output schema, the description fully specifies the return shape on success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal shape with all possible refusal_reason values. It also places the tool within its sibling context by naming ask_pipeworx and explaining the tradeoff. An agent has everything needed to select and invoke this 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 has 100% description coverage and explicitly documents that q, text, input, query, prompt, and question are all aliases for the same natural-language question. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate. There is no harm, but also no value added.

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 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the verb (answer/extract), resource (Pipeworx tool routing), and its differentiator. It explicitly contrasts with ask_pipeworx by saying 'Same routing as ask_pipeworx' but 'EXTRACTS the answer using ONLY what the tool result contains,' making the distinction concrete. This lets an agent immediately understand what this tool does and how it differs from its closest sibling.

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?

Gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also gives the when-not-to-use alternative: 'prefer ask_pipeworx for casual lookups,' and even provides a cost-based rationale ('Costs one extra LLM call'). This is exemplary routing 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 mark it read-only, idempotent, non-destructive, and open-world. The description goes well beyond these by disclosing parallel tool routing, the findings packet structure, explicit gaps[], contradictions[], hop fields, citation_uri resolution guarantees, semantic excerpting behavior, account requirements, and expected latency. There is no contradiction with 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 long but dense and mostly well-organized, front-loading the account requirement and core distinction from ask_pipeworx before diving into mechanics. A few details are reiterated in the schema, but every sentence serves a practical decision or invocation need.

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

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

Given the tool's complexity, the absence of an output schema, and the wide sibling set, the description is remarkably complete. It covers authentication, cost, alternatives, return shape, timing, limitations, citation resolvability, and depth-specific behavior, so an agent has what it needs to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by clarifying that question is natural-language and intentionally broad/multi-part, and by tying depth tiers to cost and recovery behavior, including the paid requirement for 'thorough'.

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

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

The description states a specific verb and resource: deep research over Pipeworx's 1500 structured data sources, with decomposition into facets and a findings packet. It explicitly distinguishes itself from ask_pipeworx and clarifies it is not open-web search, so an agent can tell it apart from its sibling 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 gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and names alternatives for single lookups and breaking/colloquial current-news topics. It even states behavioral consequences, such as mostly empty gaps[] in cases where the topic isn't in the structured catalog.

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?

The description goes well beyond the annotations by disclosing fan-out sources, return sections, soft-failure of the USPTO patents source, the meaning of empty sections, and the resolved:false behavior for private companies. It even warns that an empty FDA section is expected for companies with only small-molecule drugs. This is exceptionally transparent.

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

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

The description is long, but the tool is complex and has no output schema, so the density is justified. It is front-loaded with purpose and usage, then organized by return section, and each clause carries meaningful behavioral or semantic information. Slight redundancy exists around accepted input forms, but it does not harm usability.

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

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

Given the tool's complexity, the absence of an output schema, and the lack of per-source structure elsewhere, the description fully covers what an agent needs to invoke it correctly: input shapes, resolution behavior, return sections, failure semantics, and source status reporting. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that names resolve via SEC EDGAR company-name matching, that CIKs should be zero-padded, and that type accepts both 'company' and 'ticker' interchangeably with identical value shapes. These details go beyond the schema's own descriptions.

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

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

The description opens with concrete user phrasings ("Tell me about X", "research Acme") and states a specific action: producing a full cross-source profile of a US public company in one parallel call. It clearly distinguishes itself from single-pack SEC/XBRL/news lookups and from other sibling tools by naming the holistic aggregation behavior.

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

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

It explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view, and it enumerates accepted input forms. It also states the failure behavior for private companies, helping an agent know when the tool is not applicable. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare 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?

Beyond the readOnly and idempotent annotations, the description discloses compatibility_warning semantics, fee caveats, null temporal_alignment meaning, skipped-leg counters, and the rule that unknown metric_type legs are never paired. No contradiction with annotations exists.

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 and dense, but every sentence contributes distinct mode, response, or safety semantics, and it is logically front-loaded with purpose and modes before disclosures. It is not as crisp as a minimal definition, but 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?

With no output schema, the description fully carries the burden of explaining return semantics, including top_spreads_pp, compatibility_warning/codes, per-entry flags, temporal_alignment null semantics, fees_note, and skipped-leg counters. It also handles edge cases like unknown legs and pairing_unverified, making it effectively complete for correct invocation and interpretation.

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 substantial meaning by explaining that topic selects a pre-mapped event, that explicit ticker/slug override the mapped side, and that both modes run the identical token-overlap matcher. This goes beyond the raw schema definitions.

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

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

The description clearly identifies the tool's function as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, and it lays out two explicit modes. It does not explicitly distinguish itself from close sibling tools like polymarket_arbitrage or polymarket_edges, so it stops short of a 5.

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

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

The description gives clear context on when to use pre-mapped topic shortcuts versus explicit kalshi_event_ticker and polymarket_event_slug pairings, and it cautions that pre-mapped topics are often not tradeable. It does not explicitly state when to prefer alternative sibling tools, so exclusions are missing.

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

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

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?

Annotations already signal readOnly/openWorld/idempotent behavior, and the description adds substantial behavioral context: cascading internal lookups, graceful degradation if GLEIF or OpenFIGI is unavailable, ambiguous matches returning figi_candidates, unresolved IDs being stated explicitly, and identifiers labelled with their source. These are details the annotations do not convey.

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

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

The description is long but front-loaded with common user phrasings and a crisp purpose statement. Every major segment earns its place: supported types, behavior on ambiguity, unresolved handling, and input-form caveats. It could be tightened, but the density of operational guidance justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: company resolution yields CIK, ticker, company_name, LEI, FIGI, source labels, unresolved identifiers, and candidate lists; drug resolution yields RxCUI, ingredient, brand, and citation. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, providing baseline value for both parameters. The description adds meaningful semantic guidance beyond the schema, particularly for value: 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed... never the question's full noun phrase.' It also clarifies fallback matching behavior that affects how the value parameter is interpreted.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools like compare_entities and entity_profile by explicitly framing this as the identifier-lookup step, with supported entity types and examples.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains that one call replaces 2-3 manual lookups, and provides detailed input-format instructions such as passing the issuer name only, not the full noun phrase. This makes when-to-use unambiguous.

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

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

Annotations 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.