Unsplash

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the default model is free (Workers AI), while using Anthropic requires a BYO key and incurs direct user billing. This goes beyond the annotations, though it does not cover rate limits or possible error 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 two sentences long, front-loaded with the core function, and efficiently includes model defaults, return format, and use cases. Every sentence earns its place with zero 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 there is no output schema, the description compensates by explicitly listing per-model result fields ({score, confidence, signals, raw_response}) and the combined view. It also covers default model, optional Anthropic key, and practical use cases, making the tool's behavior and purpose clear for a 4-parameter tool with only one required 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?

Schema description coverage is 100%, so the baseline is 3. The description supplements the schema by clarifying the default model's cost (free), and explicitly notes that the _apiKey is a BYO key with direct payment to Anthropic. This adds semantic value beyond what the schema already provides, justifying a 4 rather than a 3.

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

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

The description opens with a specific verb ('Probe'), names the resource ('one or more LLMs'), the subject ('business / brand / product / topic'), and the concrete outcome ('score visibility (0-100) per model'). It clearly distinguishes itself from siblings by focusing on LLM knowledge visibility scoring rather than direct Q&A or research.

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

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

The description provides clear use cases ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to use the Anthropic model ('pass _apiKey to also probe Anthropic'). However, it does not explicitly contrast itself with sibling tools or state when NOT to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it routes to internal tools, fills arguments automatically, returns citation URIs, and notes it works on every tier with one fast call. It does not contradict annotations.

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

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

The description is longer than most, but it is well-structured and every sentence serves a purpose: directives, mechanism, examples, and alternative escalation paths are all present. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and does not waste words, though it is somewhat 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?

For a tool with no output schema and a broad routing purpose, the description is remarkably complete. It covers when to use, how it works, what it returns (structured answer with stable citation URIs), when to prefer alternatives, and provides multiple concrete examples. The mention of 'one fast call' and 'works on every tier' also sets performance expectations.

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 semantics beyond the schema by explaining what kinds of natural-language questions are appropriate (factual questions about real-world entities, events, numbers) and providing examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), which helps the agent formulate effective values for the 'question' parameter.

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

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

The description uses a specific verb ('routes', 'returns') and clearly identifies the resource: it routes questions to one of 5,564 tools across 1,462 verified sources and returns structured answers with citation URIs. It also distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), lists concrete trigger phrases, and gives step-up alternatives with clear criteria ('hallucination-resistant single answer', 'broad/multi-part question'). No other tool in the sibling list is as thoroughly positioned.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses experimental behavior, the current inactive candidate state, that results are compared with the stable router, and that it is a fully working router with no fallback. This adds valuable context about the tool's live experimental nature.

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

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

The description is four sentences, each contributing useful information (beta nature, current status, usage instruction, full functionality). It is slightly detailed but not wasteful, earning a 4.

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 universal router with a simple one-parameter schema and no output schema, the description covers the experimental purpose, current matching behavior, usage context, and response shape equivalence. It does not detail the return format, but the mention of 'same response shape' as ask_pipeworx provides adequate context.

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

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

Schema description coverage is 100% for all parameters (question and its aliases are fully documented). The description only says 'same arguments' and does not add further parameter meaning beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router (same 5,564 tools, same arguments, same response shape)', giving a specific verb and resource. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental edge and candidate routing improvements.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This clearly indicates when to use this tool rather than ask_pipeworx and mentions the alternative.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses the refusal behavior with specific refusal_reason values, the return object structure, and the extra LLM call cost. It also states that the tool 'fetches the data' and 'extracts' the answer, providing safety and operational context not present in 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 adds value: purpose, mechanism, return format, refusal reasons, usage guidance, and cost trade-off. It is well-structured with front-loaded intent and 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?

The tool is complex (routes across thousands of tools, has multiple refusal scenarios, and is intended for high-stakes reads), but the description fully covers behavior, return structure, and usage guidance. With no output schema, the description compensates by explicitly listing the return object and refusal reasons.

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 for all six parameters (aliases for a single natural-language question), so the baseline is 3. The description does not add parameter-specific details beyond the schema, though it does imply the question is a natural-language query that will be routed dynamically.

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

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

The description clearly states the tool's function: a hallucination-resistant answer mode that routes through the same mechanism as ask_pipeworx and extracts answers using only tool-result content. It distinguishes itself from siblings by emphasizing high-stakes reads and verifiable evidence. Specific verb 'EXTRACTS' and structured return values further clarify the purpose.

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

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

The description gives explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and explicitly recommends preferring ask_pipeworx for casual lookups. It names the alternative and provides clear when-to-use and when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: low-confidence matches short-circuit with status 'low_confidence_match' and suppress analysis fields, closed/dead markets return a blocking status, wide-spread markets carry tradeability 'illiquid_wide_spread', and resolution-rule parsing flags cancellation/void risks. These are critical operational behaviors not inferable from annotations.

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

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

The description is front-loaded with the core purpose and then proceeds into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), but it's a single unbroken paragraph without line breaks, making it harder to scan. Every sentence carries information and there's no fluff, but the structure could be improved for readability, so 4 rather than 5.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so in depth: result.market fields, result.analysis with model_probability/edge_pp/kelly_fraction_half, result.evidence keyed by source, resolver match confidence/alternatives/suggestions, parent_event extractor for partitions, news fallback fields, and safety statuses. It even includes resolution-rule risk examples with EV impact. For a complex tool, this is comprehensive.

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 three parameters with descriptions (market formats, depth enum, include_raw default), providing 100% schema coverage. The description does not add significant parameter-level semantics beyond the schema; its examples echo the schema's own examples. It focuses on output behavior rather than parameter details, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from siblings by focusing on Polymarket bet research with market slug/URL/question text input and a market-vs-model comparison. The use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') further clarify its unique scope.

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

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

The description provides explicit intended usage: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to invoke it, but it doesn't explicitly name alternatives or when-not-to-use scenarios, so it stops short of the highest bar.

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, so the safety profile is known. The description adds valuable context by enumerating the returned metadata fields (title, description, total photos, tags, cover photo, curator profile), which is behaviorally informative beyond the annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and resource. It contains no redundant words and every phrase adds meaning, making it an exemplar of 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?

Given the tool's simplicity (one parameter, output schema present, robust annotations), the description is complete. It lists the key metadata fields returned, and with the output schema available, there's no need for further elaboration. It covers the essential usage context for an agent.

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

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

With only one parameter 'id', schema description coverage is 0%, but the description's 'by id' makes the parameter's purpose obvious. The example in the schema further clarifies the format. The description adds sufficient context for the single, simple parameter.

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 ('Fetch') and resource ('metadata for a single Unsplash collection by id'), clearly distinguishing from sibling tools like 'collections' (plural) and 'collection_photos' (photos within a collection). This makes the tool's purpose immediately clear.

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

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

The phrase 'by id' and 'single collection' provides clear context for when to use this tool (when you have a specific collection id). It does not explicitly mention alternatives or exclusions, but the distinction from similarly named siblings is evident, so it earns a 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the operation's safety profile. The description adds useful behavioral details beyond annotations, such as pagination and the structure of returned photo objects (image URLs and metadata), which helps set expectations.

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

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

The description is a single, front-loaded sentence that states the action and the expected output without any verbose or irrelevant content. It is concise and effectively 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?

The tool has one required parameter, a robust annotation set, and an output schema. The description covers the operation, scoping, and output characteristics, making it sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has zero description coverage for the sole parameter 'id', but the description clarifies that it is the specific Unsplash collection id, giving the parameter its intended meaning. This fully compensates for the schema's lack of description.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'photos inside a specific Unsplash collection by id'. This precisely states what the tool does and distinguishes it from sibling tools like list_photos or search_photos.

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 context by requiring a collection id and describing the operation, making the appropriate use case obvious. However, it does not explicitly mention alternatives or when not to use this tool, which would have made the guidance stronger.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context about pagination and the returned fields (id, title, curator info), going beyond annotation coverage 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 a single, direct sentence that front-loads the primary action and includes only essential information. 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 list tool with rich annotations and an output schema, the description covers purpose, return fields, and pagination. It lacks explicit pagination control details, but the simplicity and provided schema make it sufficiently complete.

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

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

The tool has zero parameters in the schema, and the description mentions paginated order but not how to control pagination. With zero parameters, the baseline is 4; the description provides enough context without needing parameter details.

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

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

The description clearly states the tool lists featured Unsplash collections in paginated order, using a specific verb and resource. This distinguishes it from sibling tools like 'collection' (singular) and 'collection_photos'.

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 this is for listing featured collections in paginated order, giving a clear context. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous from the wording.

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 read-only, idempotent, non-destructive, but the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling for companies, sorting by primary metric, and citation URIs in the response. This goes well beyond the annotations.

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

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

The description is detailed but every sentence delivers unique information. It is front-loaded with usage examples and prioritization rule, then provides data source specifics and output characteristics. There is no filler or repetition.

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 and lack of output schema, the description covers return format (paired data + citation URIs), sorting behavior, data source details, and edge cases (off-calendar fiscal years). It is complete enough for an agent to invoke correctly without additional lookup.

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 already documented. The description adds meaning by explaining what each type parameter does (company vs drug) and what 'values' should contain (tickers/CIKs vs drug names), including examples. This elevates beyond the baseline schema.

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

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

The description states a specific action: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It clearly distinguishes from siblings like entity_profile by mentioning 'replaces 8–15 sequential lookups' and uses a specific verb ('compare') with defined resource types.

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

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

Provides explicit when-to-use guidance with trigger phrases ('X vs Y', 'which is bigger', 'rank these companies') and an explicit 'ALWAYS PREFER over sequential single-pack lookups' instruction. This makes the intended usage unambiguous relative to 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?

Despite annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds substantial context: account/paywall requirements, parallel decomposition, findings packet contents, gaps[] never invented, contradictions[] for standard/thorough, latency expectations, semantic excerpting, and citation_uri fetchability. No contradiction with annotations.

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

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

The description is long but information-dense; nearly every clause adds useful details (alternatives, output packet, depth semantics, latency). It is front-loaded with the most critical account requirement and usage caveat, though the run-on structure and parentheticals make it slightly harder to scan.

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 return values: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri fetchability. It also covers auth tiers, latency, and depth behavior, making it complete for a complex research 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%, so the schema already documents both question and depth. The description still adds value by clarifying the question accepts broad/multi-part natural language ('decomposition is the point') and by explaining depth as quick=3 single-hop, standard=3 default with gap recovery, and thorough=6 paid with an extra iterative hop.

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+resource: performs grounded multi-source research across Pipeworx's 1462 structured data sources, decomposing questions into facets and routing them in parallel. It clearly distinguishes from siblings by saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and current-news topics.

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

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

Explicit usage guidance is present: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and signed-out users are directed to ask_pipeworx. This makes when-to-use vs alternatives 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 already establish the safe read-only, idempotent profile, so the bar is lower. The description adds valuable behavioral context: it returns top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), ready to call directly without a second lookup. This goes beyond the annotations to explain the return payload and workflow.

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

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

The description is information-dense without waste. Three sentences: what it does, what it returns, and when to call it. Each sentence earns its place, and the domain list is a compact but useful scope indicator.

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 meta-purpose and lack of output schema, the description fully covers the return format (top-N results with schemas and examples), the input (natural language query), and usage context. The schema examples further illustrate usage. This is complete for an AI agent to select and invoke the tool.

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

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

Schema coverage is 100%, with every parameter described, so the description carries little parameter burden. It does reinforce that 'query' is a natural language description and mentions 'top-N' implicitly linking to 'limit', but these are already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It clearly distinguishes this meta-tool from sibling data-specific tools by stating it discovers tools across a wide range of domains (SEC filings, FDA, FRED, etc.), which none of the siblings 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?

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clarifies when to use it and implicitly when not to (when you already know the specific tool).

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

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

Annotations already declare safe read-only behavior, and the description adds meaningful context: it fans out across multiple sources, soft-fails for the USPTO API sunset, uses a GDELT→GNews fallback, and only supports US public companies. No contradiction with annotations.

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

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

The description is a single dense paragraph packed with example trigger phrases, return details, and usage notes. Every sentence contributes value, though the long list of example queries makes it 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?

Since there is no output schema, the description carries the full burden of explaining return values. It enumerates the exact fields returned, includes URIs, notes soft-fail behavior, and states input limitations—comprehensive for a multi-source tool.

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

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

The schema already fully describes both parameters (type and value) with examples and constraints. The description repeats these examples in prose but does not add meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description clearly states the tool produces a 'full cross-source profile of a US public company' and enumerates the exact outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes itself from sibling tools by explicitly positioning it as the preferred choice over chaining single-purpose lookups.

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

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

Provides explicit guidance on when to use it ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first if you only have a name'). This is clear and actionable.

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, which align with the description. The description adds useful behavioral context about clearing sensitive data and the purpose of deletion, going beyond the bare annotations. It does not contradict the annotations, though it could mention idempotency behavior explicitly.

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

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

The description is two sentences, front-loaded with the action, followed by use cases. Every word earns its place, with no wasted information or 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 simple single-parameter tool with annotations covering safety (destructive) and idempotency, the description provides sufficient context for correct usage. No output schema exists, so not explaining return values is appropriate.

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

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

Schema coverage is 100% with the `key` parameter fully described as 'Memory key to delete'. The description merely repeats 'by key' without adding new meaning, so it meets the baseline but doesn't enrich parameter understanding.

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

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

The description uses a specific verb 'Delete' and resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall. The action is unambiguous and directly states what the tool does.

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

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

The description gives explicit guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also mentions pairing with remember and recall, providing clear situational 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies that the output is a single text blob ready to drop at site-root/llms.txt, which helps the agent understand what the tool actually does without contradicting 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 concise, front-loaded with the main action, and every sentence adds value. It includes a clear one-line summary, a brief process explanation, and a 'Useful for' list—all in three sentences without unnecessary fluff.

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

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

Given the tool's simplicity, the complete input schema, and the annotations, the description covers the essential aspects: what it does, how it works, the output format, and typical use cases. It explicitly states the output is a text blob, which is important since there is no output schema.

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

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

The input schema already covers both parameters fully (url and max_links with descriptions), so the description does not need to add much. It mentions 'key links' but does not explain max_links; however, the schema's own description handles this. Baseline of 3 is appropriate since the schema provides the heavy lifting.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It also names the output format and the intended audience (AI crawlers), which distinguishes it from sibling tools like ai_visibility_check that focus on checking presence rather than generating the file.

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

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

The description provides concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), making the intended context clear. It does not explicitly mention when not to use the tool or name alternatives, but the use cases are specific enough to guide 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 read-only and safe behavior. The description adds useful context beyond that: the feed is public, editorial, and returns paginated photo objects with URLs and metadata. It does not contradict annotations and provides insight into the return format and ordering options, though it omits details on how pagination is controlled.

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 front-loads the primary action ('Fetch'), specifies the resource, and lists key attributes (ordering, output type). Every word contributes to understanding, with no fluff or redundancy. It is appropriately 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?

For a simple list tool with strong annotations and an output schema, the description sufficiently covers the key behaviors and return type. However, it leaves gaps around pagination control and does not explicitly differentiate from sibling listing tools, so it is not fully complete for complex usage scenarios.

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 defines zero parameters (empty properties) despite examples showing page and per_page, creating ambiguity. The description mentions 'paginated' and ordering but does not explain how to specify the page, per_page count, or order (chronological vs popular). The baseline for zero params is 4, but the description fails to clarify the intended optional parameters, resulting in a lower 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 tool fetches Unsplash's public editorial feed of recently curated photos with specific ordering options (chronological or popular) and describes the output. This distinguishes it from sibling tools like search_photos or user_photos by specifying the exact resource and scope.

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

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

The description implies use cases through 'editorial feed' and 'curated photos' but does not explicitly state when to prefer this over related tools like collection_photos or topic_photos. There are no exclusions or alternative recommendations, leaving the agent to infer the appropriate context.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds the caller-scoped nature and the return fields, providing context beyond the annotations. No contradictions found.

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

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

The description is concise and front-loaded: the first sentence states the action, the second lists return fields, and the third gives usage context. Every sentence serves a purpose with no fluff.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is sufficiently complete. It lists return fields and usage context, which is valuable. It does not mention pagination or ordering, but those are not critical for this low-complexity tool.

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

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

The schema covers the single parameter (include_inactive) with a description, giving 100% schema coverage. The description does not add additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'List the caller's active subscriptions.' It specifies the resource (subscriptions) and scope (caller's active), and lists return fields. It does not explicitly mention sibling tools like subscribe or unsubscribe, but the purpose is unambiguous.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool, though it doesn't explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by enumerating exactly what metadata is returned (image URLs in multiple sizes, EXIF, location, tags, photographer). It does not contradict annotations.

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

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

The description is a single well-structured sentence, front-loaded with the verb and resource. It includes specific details without 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?

With an output schema present, the return structure is already specified. The description complements it by listing the metadata categories, providing a good overview. It could mention error behavior or rate limits, but for a simple single-photo fetch this is 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 description coverage is 0%, so the description should compensate by explaining the id parameter's format, provenance, or required format. It merely says 'by id', which adds nothing beyond the schema's example and property name. The minimal compensation makes this a weak point.

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

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

The description uses a specific verb ('Fetch') and clearly identifies the resource ('full metadata for a single Unsplash photo by id'). It lists the key metadata categories (URLs, EXIF, location, tags, photographer), which distinguishes it from sibling tools like photo_download, photo_random, and photo_statistics.

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 implies the use case: when you have a photo ID and need comprehensive metadata. It does not explicitly name alternatives or exclusions, but the scope is unambiguous. A brief mention of 'use search_photos first to find IDs' would have earned a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by explaining the 'trigger event' behavior and the API guideline requirement. It discloses the side-effect of tracking and the return of a download URL, which goes beyond the structured 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, front-loaded sentence that covers the main action, purpose, and a key requirement without unnecessary detail.

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

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

Given the tool's simplicity (one parameter, rich annotations, output schema), the description is complete: it explains the trigger event, the returned URL, and the mandatory usage context. No critical 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 0%, but the description clarifies the only parameter 'id' is a photo ID ('for a photo by id'). Combined with the example in the schema, this is sufficient for a single simple parameter.

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 it triggers the Unsplash download-tracking event and returns the download URL, which is a specific verb+resource+outcome. It clearly distinguishes from sibling tools like list_photos/photo by focusing on the tracking event and URL return.

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

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

The description provides explicit usage context: 'must be called before presenting the download link to users per Unsplash API guidelines.' This tells when to use it, though it does not name alternative tools or say when not to use it.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, so the description only adds minor context: the ability to return multiple photos and apply filters. It does not detail pagination, rate limits, or response structure, but the output schema covers return values. This is adequate but not overly rich.

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 front-loads the primary action ('Retrieve one or more random Unsplash photos') and efficiently groups the filter options. No redundant or filler words are present, making it 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?

Given the presence of annotations (readOnly, idempotent, openWorld) and an output schema, the description is fairly complete for this simple tool. It covers the core behavior and filter options, but does not mention count or how extras are passed in practice; this leaves minor ambiguity for an agent. Overall, it is contextually 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?

The schema defines zero properties, so the description's mention of 'extra params' (query, orientation, collections, topics, username, content_filter) adds essential semantic value beyond the empty schema. However, it omits the 'count' parameter shown in examples, and does not specify parameter types or formats. Still, the listed filters provide a solid baseline.

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

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

The description clearly states the tool retrieves random Unsplash photos, distinguishing it from sibling search/list tools. The verb 'Retrieve' and specific resource 'random Unsplash photos' make the purpose unambiguous. Mentioning optional filters further clarifies scope without confusion.

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: use this for random photo retrieval, and lists the available filter parameters. It does not explicitly name alternatives like search_photos or list_photos, but the random nature implies when to use this tool. No exclusionary guidance is needed since the use case is evident.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description is not burdened with safety claims. It adds context about the time-series window behavior ('supports resolution and quantity to control the time-series window'), which is helpful. However, it does not discuss potential errors, rate limits, or response format beyond what the output schema provides.

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, front-loaded sentence that states the main purpose first and then adds the optional parameter behavior. Every word earns its place, and it avoids unnecessary detail.

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

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

Given the tool's simplicity, an output schema exists, and annotations cover safety, the description is reasonably complete. It explains the key parameters and the time-series nature, which is the main functional nuance. The only gap is the ambiguity around 'resolution' caused by the conflicting schema example, but the description itself is sufficient for a competent agent to infer 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 the description must compensate. It explains that 'quantity' is a 1-30 range and 'resolution' relates to time granularity ('days'), adding meaning beyond the bare property names. However, the schema example shows resolution as '1920x1080', which is an image resolution, creating confusion and reducing clarity. The description is not sufficient to fully resolve parameter semantics.

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

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

The description clearly states the action ('Fetch'), the resource ('view, download, and like statistics for a single Unsplash photo'), and the scope ('by id'). This distinguishes it from siblings like 'photo', 'photo_download', and 'list_photos', which handle other aspects of photos.

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 the tool should be used when retrieving stats for a single photo, and mentions the ability to control the time-series window with resolution and quantity. It does not explicitly exclude alternatives or state when not to use it, but the context is clear enough for a focused tool.

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

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

Annotations are all false, so the description carries the full burden—and it delivers: it discloses rate limits, free/no quota, claim_token return flow, daily digest processing, roadmap impact, and the instruction not to paste end-user prompts. Nothing contradicts 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 every sentence earns its place: use cases, exclusions, token flow, rate limits, and scope. It is front-loaded with the core purpose and all additional details are behaviorally relevant.

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

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

For a feedback tool with no output schema, the description thoroughly explains what happens after filing (claim_token, later querying) and covers all important context: scope, use cases, constraints, rate limit, and human review process. No critical gaps.

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

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

Even though schema coverage is 100%, the description adds significant meaning: claim_token is explained as a way to check resolution later, message guidance gives concrete advice ('Be specific, 1-2 sentences, 2000 chars max'), and the 'don't paste end-user prompt' instruction enriches the context object 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?

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools like ask_pipeworx by scoping to feedback about Pipeworx tools and explicitly excepting other MCP servers' 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?

It gives explicit when-to-use conditions: bug, feature/data_gap, praise. It also states when NOT to use it (tools from other MCP servers) and what to do instead ('file it with that server instead'). This is model guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the description's burden is lower. It adds valuable context: derived from CF analytics-engine, no PII, just (pack, tool, count), and caching behavior (5min-1h depending on window), 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 front-loaded with the core function in the first sentence, followed by a concise 'Useful for' list and a brief data provenance/caching note. Every sentence adds value; no fluff.

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

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

The tool is simple: one optional parameter, no output schema. The description covers what is returned (top tools, packs, call volume), privacy, caching, and usage contexts. It is complete for invoking and understanding the 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% — the 'window' parameter has a detailed description with defaults and semantics ('24h (default) | 7d | 30d. Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only restates the window options without adding new parameter-level meaning, so baseline 3 is appropriate.

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

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

The description uses a specific verb 'Returns' and identifies the resource: top tools, top packs, and total call volume over a recent window. The first sentence 'What other AI agents are calling on Pipeworx right now' sets a clear scope that distinguishes it from sibling tools like discover_tools, which likely explore general tool info.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical choice, and checking alignment. It implies using this before asking a question, but does not explicitly name alternatives or when-not-to-use, leaving a gap in comparative guidance.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, but the description adds rich behavioral detail: placeholder slug filtering, partition_sum deviations >3pp triggering signals, Jaccard similarity threshold, and the FILL CHECK caveat that realizable_edge_pp ≤ 0 means not tradeable. This goes well beyond the static 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 with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose. Despite length, every sentence adds operational value—no filler or repetition of schema. The density 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 explains the response shape: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context; partition_check fields; and fill_check fields. It covers edge cases, filtering rules, and trade guidance, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both params, but the tool description adds significant semantic meaning: event expects a Polymarket event slug or full URL; topic expects a seed question and performs cross-event search. It provides concrete examples for each and explains the downstream behavior each param triggers.

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 a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from siblings by naming the two modes (event, topic) and referencing fill_check and polymarket_fill_risk as separate concerns.

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 each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' Recommends event for specific markets and topic for cross-event scanning, even naming when cross-event mode 'catches ... patterns that single-event misses.' Also points to polymarket_fill_risk for custom sizing, an alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description goes much further. It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), the internal segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), the 24h-move warning, and the diagnostics structure for empty segments. It also reveals the Kelly cap (0.25) and the slippage model, providing rich behavioral context beyond the annotations.

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

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

The description is a dense ~360-word paragraph filled with implementation-specific details like per-sport alpha values (tennis 1.02, soccer 1.10, MMA 1.15), placeholder slug patterns, and Run 8 relaxation thresholds. While the purpose is front-loaded, these details are not necessary for an agent to select and invoke the tool correctly, harming scannability. The lack of clear formatting or section breaks makes it harder to parse than an optimized two-sentence summary.

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 must explain return values and it does so thoroughly. It details the response top-level structure (by_segment with model_driven, structural_arbitrage, concentrated_longshot), fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also explains the per-opportunity fields (edge_pp_net, kelly_fraction, etc.) and the tradeable-edge knobs. For a tool with 9 optional parameters and three model families, the description is complete.

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

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

The input schema already provides 100% coverage with detailed descriptions for all 9 parameters. The description adds meaningful supplementary semantics, such as explaining that min_liquidity/max_spread_pp 'drop opportunities where edge isn't realizable' and clarifying that min_kelly does not apply to partition_overround because partition arbs return parent-level kelly_fraction_half=0 by design. This adds value beyond the schema without repeating it.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the data source (Pipeworx), and the output (opportunities). The phrase 'Built for what should I bet on today' further clarifies its role among siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides clear usage context: it is designed for daily edge discovery without manually paging markets. It describes the three output segments and explains the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and why Fed bets are excluded from ranking. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: snapshot writes occur on cache-miss (so gaps mean no scan), history depth is bounded by a 60-day TTL, and decay numbers are computed on daily closes of edge_pp_net, not intraday. These details go well beyond annotation hints and set proper expectations about data availability and calculation methodology.

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 into clear sections: purpose, args, response, and limits. Every sentence provides useful information, and the use of labels 'Args:', 'RESPONSE:', 'LIMITS:' makes it scannable. It is more verbose than strictly necessary, but the complexity of the response format and caveats 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?

There is no output schema, so the description must explain return values, and it does so thoroughly: tracked[], expired[], and snapshot_dates[] are each defined with their contents and implications (e.g., median lifespan as 'competition clock'). It also covers historical limitations (60-day TTL, snapshot gaps) and calculation details. Given the tool's complexity, this description is complete.

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

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

Schema coverage is 100%: both parameters are described in the schema. The description repeats the same info ('days (lookback, default 14, max 30), window (snapshot family, default "1wk")') without adding new semantics beyond what the schema already provides. It does not clarify values, formats, or edge cases, so it meets the baseline but does not elevate it.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical edge tracking rather than current 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 implies when to use this tool: when you need to know if an edge is fresh or decaying, comparing 'a fresh wide edge and a 3-week-old wide edge.' It notes it's built from polymarket_edges snapshots, which signals a complementary role, but it does not explicitly name alternatives or state 'use this instead of X.' Clear context but no explicit exclusions.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds substantial behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), flags thin_legs[], and warns that partial basket fills convert an arb into an unhedged directional position. It also explains the interpretation of size_usd in both modes, which goes far beyond the annotations.

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

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

The description is well-organized with clear visual cues (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded with its core purpose. It is long, but the tool is complex with two modes and many outputs; every section earns its place by explaining mode-specific behavior and return fields. A slight trim of the exhaustive output lists would improve conciseness without losing 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 complexity and the absence of an output schema, the description compensates fully by enumerating the return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk). It also covers prerequisites, mode selection, and risk explanation, making it complete for an agent to decide and even anticipate results.

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 has 100% parameter description coverage, so the description's additions are bonus value. It clarifies the mutual exclusivity of 'market' vs 'event' and adds the nuance that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode. This is genuinely helpful beyond the schema, though the schema already covers most of the mechanics.

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 a crisp, specific purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly names the resource (CLOB order book) and differentiates two modes (single-market vs basket), which clearly distinguishes it from related polymarket tools such as polymarket_arbitrage and 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 final paragraph gives explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It names the alternative tools and provides a concrete threshold, plus a rationale (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk). This leaves no ambiguity about when to choose this tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description reveals significant behavioral detail: compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the concrete example of non-equivalent bet shapes (range_bucket vs cumulative_threshold). It also exposes the limitation that many shortcuts return warnings, providing honest expectations. This is a model of behavioral disclosure.

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 exceptionally well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). The opening sentence front-loads the core purpose. Every sentence carries meaningful information, though some concepts (e.g., bet-shape equivalence) are repeated in the safety fields section. The density is justifiable given the tool's complexity, but a bit tighter editing could improve scannability.

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 takes full responsibility for explaining return values. It covers leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped_cross_type/subtype counters. It also handles edge cases like mismatched bet shapes, unrelated events, and temporal misalignment. This is comprehensive for a tool of this complexity.

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

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

Although schema coverage is 100%, the description adds substantial meaning to each parameter. It lists all 10 topic values with examples, explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and distinguishes custom pairings from pre-mapped mode. This goes far beyond the schema's terse property 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 a specific verb+resource construction: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from sibling Polymarket-only tools like polymarket_arbitrage or polymarket_edges by emphasizing the cross-venue comparison. The two modes and response structure further clarify exactly what the tool computes.

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 states when to use the tool: for cross-venue Kalshi–Polymarket spreads, with two explicit modes (pre-mapped topic shortcuts or explicit event ticker/slug). It cautions that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable,' which is a useful exclusionary note. However, it does not explicitly name alternative tools for same-venue comparisons or mention when not to use this tool beyond the caution.

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, so safety is covered. The description adds valuable context about scoping to an identifier (anonymous IP, BYO key hash, or account ID) and the listing behavior when the key is omitted, which goes beyond the 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 three sentences long, front-loaded with the primary action, and every sentence adds distinct value: what it does, when to use it, and how it relates to sibling tools. No redundancy or 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 simple read-only tool with one optional parameter and no output schema, the description is fully adequate. It covers purpose, usage, scoping, and peer relationships without needing to explain return values or complex behavior. The provided annotations further round out the context.

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

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

Schema description coverage is 100%, and the schema already explains the 'key' parameter well, including the omit-to-list behavior. The description adds illustrative examples of values but does not provide additional parameter syntax or format details, so it aligns with the baseline for full schema coverage.

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

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

The description uses a specific verb ('Retrieve') and resource ('a value previously saved via remember') while also covering the alternative behavior of listing all keys when the key argument is omitted. It clearly distinguishes this tool from its siblings 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?

The description explicitly states when to use the tool ('Use to look up context the agent stored earlier') and gives concrete examples (target ticker, address, research notes). It also indirectly highlights when to use alternatives by pairing with 'remember to save, forget to delete', and explains the benefit of avoiding re-deriving information.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the side effect of mark_read (flags events read and affects future calls), the shape of returned items, and the existence of an equivalent GET endpoint. It does not mention auth or rate limits, but those are less critical given the annotations. The mark_read behavior is a notable addition since it reveals a state-changing aspect.

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 purpose. Each sentence adds concrete detail: what it returns, how to filter and mark read, and a note on polling with an alternative URL. There is no redundant or wasted wording, making it both concise and well-structured.

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

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

Given there is no output schema, the description provides essential return-field details (source, citation_uri, raw payload) and explains the mark_read semantics. It also covers the full usage flow (filtering, polling) and gives an external access path. With all params documented in the schema and safety covered by annotations, this description is highly 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?

The schema already describes all 5 parameters, so baseline is 3. The description adds value by giving an example type (sec_8k), explicitly showing that type and since can be combined, and clarifying the consequence of mark_read (next call only shows newer). These details go beyond the basic property 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 'Pull fired events from your subscription feed', which clearly names a specific verb and resource. It distinguishes itself from siblings like recent_changes by emphasizing the evaluator-written persisted feed and the return payload contents. This makes the tool's unique purpose immediately clear.

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

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

The description explains usage context: how to filter by type and since, the mark_read option for incremental reads, and states that polling is fine. It also offers an alternative HTTP endpoint for scripts/dashboards, which is a helpful alternative. However, it does not explicitly compare to sibling MCP tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses key behaviors: it fans out to multiple sources in one parallel call, has a fallback chain (GDELT preferred, GNews on rate-limit/5xx), and a soft-fail for USPTO due to API sunset. It also explains the output structure (changes[] grouped by source, citation URIs), providing transparency not covered by 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 examples, then explains sources, parameters, output, and alternatives in a logical flow. There is no fluff or repetition, and it remains readable despite the 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 sources, fallbacks, no output schema), the description covers everything an agent needs: input formats, source behavior, output shape, and an alternative tool. It even mentions a limitation (USPTO soft-fail). No critical context is missing for safe and correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning: it reinforces that `since` accepts ISO or relative shorthand and suggests '30d' or '1m' for typical monitoring, but this is a minor addition to what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states it provides a change feed for a company over a time window, with examples like "What's new with X". It specifies the resource (company) and the action (getting recent changes), and explicitly differentiates from entity_profile by saying 'Use entity_profile instead when you want the static 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?

It gives concrete use cases ("updates on Acme") and explicitly mentions an alternative tool (entity_profile) for static profiles, with the distinction being time-window vs. all-time. It also explains the sources (SEC, GDELT/GNews, USPTO), which helps decide when to use this tool.

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

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

Annotations declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds context beyond annotations: key-value scoping by identifier, retention policy (24h anonymous vs persistent authenticated), and cross-session persistence. No contradictions, though it doesn't explicitly address overwriting behavior, which is partially covered by the idempotent hint.

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, tightly written, front-loaded with the primary action, includes usage signals and companion tools. Every sentence earns its place with no fluff or 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?

For a simple key-value write tool with full schema coverage and informative annotations, the description covers purpose, usage context, persistence, scope, and companion tools. 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?

Input schema covers 100% of parameters with descriptive examples. The description adds semantic context that the key is scoped by the agent's identifier, which informs how to construct keys, and clarifies the value is any free-form text. This goes beyond the schema, but the extra value is modest given the schema already provides good guidance.

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

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

The description opens with a specific verb+resource ('Save data the agent will need to reuse later') and clearly distinguishes from sibling tools by explicitly naming recall and forget for retrieval and deletion. It also clarifies cross-session scope, 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?

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples. Also tells when not to use by pointing to recall/forget as the retrieval/deletion counterparts, giving clear alternatives.

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

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

The description goes well beyond annotations. It discloses that LEI/FIGI enrichment degrades gracefully (fallback behavior), that each call cascades through several internal endpoints, and that unresolved identifiers are explicitly listed rather than omitted. All annotations (readOnlyHint, etc.) are consistent with the described read-only 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 comprehensive but slightly verbose with extensive inline details about the company resolution process. While well-structured and front-loaded, the sentence about company identifiers could be trimmed. Still, every major idea is relevant.

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

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

Given the tool's complexity (multi-source resolution, multiple identifier types, graceful degradation), the description is remarkably complete. No output schema exists, but the return structure is described in sufficient detail. The agent can fully understand inputs, behavior, and outcomes without external references.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining that for company type, input can be ticker, CIK, ISIN, or name, and for drug type, brand or generic name. It also details how ISIN resolves via GLEIF mapping. This extra context justifies a 4.

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

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

The description clearly states that this tool resolves user-spoken names to canonical/official identifiers, listing specific examples like ticker, CIK, LEI, and RxCUI. It specifies the supported types 'company' and 'drug' with detailed explanations of what identifiers each returns, distinguishing it from sibling tools that likely don't perform entity resolution.

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

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

The description explicitly tells the agent to 'Use FIRST whenever you have a name but need an ID.' It provides concrete query patterns (e.g., 'What's the ticker for…') and notes that this tool replaces multiple manual lookups. No sibling tool appears to serve the same purpose, making usage 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, and the description adds valuable behavioral context: it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. No contradiction with annotations; the methodology is 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?

Three sentences, front-loaded with the core purpose, then how it works and a use case. Every sentence adds value with no fluff or 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?

For a tool with no output schema, the description covers what, when, how, and the return format (ranked list with score/confidence/signal density). Minor gaps exist (e.g., ranking methodology details) but are not essential for selection.

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 detailed property descriptions, so the baseline is 3. The description restates the 'entities' concept but adds no new parameter-level semantics beyond what the input schema already provides (e.g., first entity as subject).

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 ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and distinguishes itself from the sibling ai_visibility_check by explicitly noting it probes each entity and ranks the results.

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 a clear use case ('competitive AI-marketing audits') and a concrete example question ('does Claude know about us as well as our competitors?'). It implies the alternative of using ai_visibility_check for single-entity checks but does not explicitly state when not to use this tool.

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

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

Beyond the readOnly/idempotent annotations, it reveals composite fan-out, graceful degradation, 5-30s bundlephobia first measurement, and sources_failed behavior. It also notes NPM-only v1 limitation, adding operational 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?

Despite length, the description is dense and well-structured: core purpose, usage triggers, return fields, ecosystem limit, failure behavior. No filler; each clause adds information.

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

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

For a composite tool with no output schema, it enumerates return fields, links, alternatives, and error behavior. Combined with annotations, an agent can invoke accurately and set expectations.

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

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

Schema covers both package and version with full descriptions including scoped packages and default behavior. The description adds no extra parameter-level semantics beyond schema, so baseline 3 is appropriate.

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

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

The description opens with a specific composite check for npm packages, naming both deps.dev and bundlephobia and the exact data points. This clearly differentiates it from sibling tools like scan_competitor_ai_presence.

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 provides direct usage triggers ('is X safe / popular / small' or 'what does adding lodash cost me') and explicitly excludes non-npm ecosystems, pointing to deps.dev:version as the alternative. That's effective 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?

The annotations already declare the tool as read-only and idempotent, so the safety profile is covered. The description adds useful behavioral details beyond annotations: paginated results and the specific return fields (image URLs, dimensions, photographer info, alt text).

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, concise sentence that front-loads the action and includes only necessary information. Every phrase adds value: search by keyword, required, pagination, and return content.

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

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

Given the tool's simplicity (1 parameter, no nested objects) and the presence of an output schema, the description is complete. It covers pagination and return fields, which are the key behavioral aspects, and the annotations provide safety context.

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

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

With 0% schema description coverage, the description must compensate for explaining the query parameter. It does label it as 'keyword' and states it is required, providing some semantic meaning. However, it lacks extra detail like format or example (though the schema's examples help), so it barely meets a baseline level.

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: searching Unsplash photos by keyword. The verb 'Search' is specific, the resource is defined, and it distinguishes itself from sibling tools like list_photos and photo_random by emphasizing keyword-based search.

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

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

The description implies when to use this tool (when you have a keyword to search for) and provides clear context about pagination. It doesn't explicitly name alternatives, but the context is unambiguous enough to guide 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?

Beyond the readOnly/idempotent annotations, the description discloses specific mechanics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also promises output structure (offsets and similarity scores), giving the agent accurate expectations for behavior and 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?

The description is dense but well-organized: it states the core function first, then the output, use case, complementary tool, and technical constraints in sequence. No sentence is filler; each adds actionable information for an agent deciding whether and how to call the tool.

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

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

For a tool with no output schema, the description fully specifies the return contract: 'get back the top-N passages with character offsets and similarity scores.' It also covers the input cap, truncation flag, and the recommended workflow with ask_pipeworx_grounded, so the agent has all necessary context to select and invoke the tool correctly.

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

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

The input schema already covers 100% of parameter descriptions, so the baseline is 3. The description adds operational context—'the text you already pulled' and 'top-N passages'—which reinforces how text, query, and limit are used together. It also mentions the 200K truncation flag, which is behavior that reflects on the text parameter.

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 'Semantic search INSIDE a fetched record,' which names the exact verb, resource, and scope. It differentiates from siblings like ask_pipeworx_grounded by explicitly framing search_within as operating on already-fetched text, and it lists concrete outputs (passages, offsets, similarity scores).

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 includes an explicit 'Use when' clause: 'when the record is too big to cram into the prompt.' It also names a companion tool and explains how to combine them: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and how-it-fits 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 indicate this is a write operation with external side effects and idempotent, and the description adds significant context: OAuth requirement, type-specific behavior, phone verification, and SMS caps. It does not contradict annotations, though it doesn't explicitly discuss idempotency behavior or duplicate subscriptions.

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

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

The description is information-dense but reasonably structured: it leads with the core purpose and return value, then types and delivery. It is longer than a typical tool description but every sentence adds meaningful detail, so it earns its 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?

For a tool with no output schema and complex parameter semantics, the description covers the necessary invocation context: what it creates, how to use each type, delivery options, and constraints. It could mention webhook signing (though covered in schema) and idempotency, but overall it's sufficiently complete.

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

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

Schema has 100% parameter description coverage, so baseline is 3. The description adds value by explaining the always-on feed channel (not a schema param), giving worked examples for each subscription type, and clarifying OAuth/verification constraints beyond the schema.

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. This distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 context on when to use it (for monitoring events), required OAuth account, and how to consume the always-on feed (via recent_alerts or the registry URL). It does not explicitly name alternatives like list_subscriptions for managing existing subscriptions, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating it draws from the 'live catalog of thousands of tools' and returns 'category-bucketed example questions', giving insight into the dynamic nature and output structure beyond what annotations provide.

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

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

The description is a dense paragraph, but it is front-loaded with the core purpose ('onboarding entry point') and includes necessary examples, return format details, and usage instructions. Each sentence adds value, though it could be slightly trimmed without losing meaning.

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 compensates by specifying the return content (category-bucketed example questions with tool + argument shape) and covers the main use cases. The rich annotations (read-only, open-world, idempotent) complement the description, making the tool behavior sufficiently clear for a simple parameter set.

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 describes the 'topic' parameter fully, listing all accepted values and the omission behavior. The description adds examples like 'finance', 'pharma', 'betting' but does not introduce new semantics beyond the schema. Given schema description coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions, each with the exact tool and argument shape. It uses specific verbs ('returns', 'use FIRST') and distinguishes itself from sibling tools like 'discover_tools' by emphasizing its role in learning what to ask Pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments for a full spread or with a 'topic' to focus. It also mentions the alternative meta-tools (ask_pipeworx, entity_profile, etc.) that the user might learn to call, giving clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying exactly what metadata is returned (title, description, total photos, cover photo, top contributors), which is valuable beyond the annotations. This goes beyond a simple scoping constraint and clarifies the nature of the operation.

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, front-loaded sentence that covers the action, the resource, the input format, and the output contents. No superfluous words or repetition of schema/annotations. Every phrase earns its place.

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

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

For a tool with one parameter, clear annotations, and an output schema, the description is sufficient. It states what the tool does, how to address the topic, and what will be returned. No additional behavioral or return-format details are necessary because the output schema is present.

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 only defines a string parameter with an example. The description compensates for the 0% schema coverage by explicitly stating the parameter is 'id or slug' and giving an example ('animals'), which fully explains the expected value format and meaning. This is exactly the kind of clarification the description should provide.

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

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

The description clearly states the verb ('Fetch') and the specific resource ('metadata for a single Unsplash topic'), with input via 'id or slug'. It distinguishes itself from siblings like 'topics' (plural list) and 'topic_photos' by focusing on the topic's metadata rather than the topics list or photos.

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 this tool: when you need metadata for one specific topic, identified by id or slug. It doesn't explicitly name alternatives or state when not to use it, but the 'single' keyword and the inclusion of metadata fields provide clear context for its intended use, without exclusions.

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 false. The description adds value by disclosing pagination and the contents of the returned objects (image URLs, EXIF, photographer info), which goes beyond the annotations. No contradiction.

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

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

One well-structured sentence that front-loads the purpose and then lists return characteristics. Every word earns its place 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 simple one-parameter tool, rich annotations, and available output schema, the description covers purpose, parameter semantics, return format, and pagination. A minor gap is the lack of explicit guidance on pagination controls or when to choose a sibling tool, but overall it is complete enough for correct usage.

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

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

The only parameter, id_or_slug, has no schema description (0% coverage), but the description explicitly states it can be an id or slug, providing essential meaning. It lacks format examples or details, but this is sufficient for a single parameter.

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

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

The description uses a specific verb 'List' and clearly identifies the resource: photos belonging to a specific Unsplash topic by id or slug. This distinguishes it from sibling tools like collection_photos, list_photos, and search_photos.

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 implies when to use this tool—when you need photos from a specific Unsplash topic—but it does not explicitly mention alternatives or when not to use it. That prevents a 5, but the context is unambiguous enough for a 4.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds the specific return fields (id, slug, title, description, cover photo, curator), which gives useful context beyond the 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 a single concise sentence that front-loads the action and resource, then lists the return fields. It contains no filler or redundancy, earning a perfect score.

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

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

The tool is simple with strong annotations and an output schema present. The description explains the return value structure, so the agent knows what to expect. It is complete for a list-type tool with no side effects or complex requirements.

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

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

The tool has zero parameters, and the schema description coverage is effectively 100% as there are no properties. The baseline for zero parameters is 4, and the description does not need to compensate. No parameter semantics are missing, though the schema examples hint at 'per_page' which is not documented, but this does not affect the 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 tool lists Unsplash editorial topics, using the specific verb 'List' and identifying the resource as curated content channels. It distinguishes itself from siblings like 'topic' (which likely fetches a single topic) and 'topic_photos' by focusing on the collection-level list.

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 browsing all editorial topics but does not explicitly contrast with sibling tools or provide when-not-to-use guidance. However, the context is clear and sufficient for a list endpoint.

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

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

The description adds meaningful behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and preservation of historical events via recent_alerts. This complements the idempotentHint and destructiveHint 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 two sentences, front-loaded with the action, and every sentence adds value: the first defines the operation, the second explains ownership and side effects. 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 single-parameter tool with rich annotations and no output schema, the description covers the purpose, side effects, ownership constraint, and downstream impact on recent_alerts. It's fully 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% and the id parameter is well-described as 'Subscription id (uuid) returned by subscribe'. The description reinforces 'by id' but doesn't add new parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation, and adds unique constraints like ownership enforcement and deactivation rather than deletion.

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

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

The description implicitly conveys when to use the tool (cancel a subscription) and mentions the id comes from subscribe, hinting at the workflow. It doesn't explicitly name alternatives or exclusions, but sibling context and the schema reference to subscribe provide sufficient 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, destructiveHint=false, so the safety profile is known. The description adds that the profile is 'public', which is a useful behavioral detail, and enumerates the returned fields. However, it does not disclose error handling (e.g., invalid username) or rate limits, and the field list may already be in the output schema.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently communicates the tool's purpose, making it 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 tool's low complexity (one parameter), the presence of an output schema, and comprehensive annotations, the description is complete. It covers the essential behavior and scope without requiring additional context.

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

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

With schema description coverage at 0%, the description must compensate. It refers to 'given username', which identifies the single parameter and its role. For a simple string parameter, this is adequate, though it does not add constraints like format validity or case sensitivity.

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 action ('Fetch') and resource ('public Unsplash profile for a given username'), listing specific fields (bio, location, counts, portfolio URL). This distinguishes it from sibling tools like user_photos and user_likes, which fetch different aspects.

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 when to use the tool: when a user's public profile information is needed. It does not explicitly mention alternatives or exclusions, but the specificity of 'profile' makes the use case obvious.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds value by disclosing the paginated return format and contents (image URLs, photographer, metadata), which goes beyond structured 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?

A single sentence that is front-loaded with the action and outcome, with 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?

With one parameter, rich annotations, and an output schema, the description adequately covers the tool's purpose, return type, and safety profile. No significant gaps.

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

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

Schema coverage is 0%, but the description clarifies that the 'username' parameter is a specific Unsplash username, adding meaning beyond the plain string type. It doesn't detail format but is sufficient for the single parameter.

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

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

The description uses a specific verb ('List') and resource ('photos that a specific Unsplash username has liked'), clearly distinguishing it from siblings like user_photos (uploaded photos) and search_photos.

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 it (when you need a user's liked photos) but doesn't explicitly mention alternatives or exclusions. Sibling tool names provide context but aren't referenced.

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 pagination behavior and the nature of returned data (photo objects with URLs, likes, metadata), which adds context beyond the readOnlyHint and idempotent annotations. No side effects are stated, but the read-only nature is already covered by annotations, and the description complements them 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 a single, front-loaded sentence that immediately states the core action and resource, then adds relevant return details. Every word contributes to understanding, with no redundant information.

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

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

The tool is simple with one required parameter, and the output schema exists, so the description does not need to detail return values. The description covers the essential behavior (listing a user's photos with pagination) and together with the read-only annotations, it provides a complete picture for a straightforward tool.

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

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

The input schema provides no description for the 'username' parameter (0% coverage). The description clarifies that it is an Unsplash username, but does not elaborate on format, case sensitivity, or relationship to other user-related tools. Since it offers partial semantic value but leaves room for further specification, a 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's action ('List') and resource ('photos uploaded by a specific Unsplash username'), distinguishing it from sibling tools like user_likes or search_photos. It also specifies the return type (photo objects with URLs, likes, metadata), making its function unambiguous.

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

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

The description implies the primary use case: retrieving a specific user's uploaded photos by username. It does not explicitly name alternatives or scenarios where this tool should not be used, though the 'specific Username' phrasing provides contextual clarity, warranting a 4 rather than 5.

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

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

Annotations already declare read-only, idempotent, and open-world behavior, but the description adds valuable error semantics: 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim' and clarifies 'unsupported' vs 'could_not_verify'. This goes well beyond the annotations.

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

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

The description is dense but every sentence carries unique information: trigger phrases, purpose, dual-pipeline logic, return value structure, error semantics, and a comparison to manual composition. It is structured to front-load the most useful guidance and uses clear formatting (e.g., 'IMPORTANT for callers').

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

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

Given no output schema, the description compensates by listing the verdict enum, citation format, and detailed explanation of failure modes. It fully specifies the tool's behavior for both the structured and grounded paths, making it sufficient for an agent to invoke correctly without external hints.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds example claim inputs and explains tolerance_pct's role ('Overrides the tolerance implied by the claim wording'), but this largely mirrors the schema. It neither harms nor significantly enriches the provided parameter docs.

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 trigger phrases and an explicit statement: 'natural-language claim verification against authoritative sources.' It clearly identifies the verb (verify/check) and resource (claims), and distinguishes itself from siblings by noting it replaces 4–6 sequential calls for fact-checking.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the dedicated fast path for company-financial claims vs. the grounded fallback for any other claim, and names the alternative manual workflow ('Replaces 4–6 sequential calls').

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