Europeana

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. Description adds useful behavioral context: default model is Workers AI Llama-3.3-70b (free), BYO key for Anthropic, return format includes per-model {score, confidence, signals, raw_response}. 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?

3-4 sentences with front-loaded purpose. No wasted words. Every sentence adds value (purpose, defaults, return format, use cases).

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

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

No output schema, but description explains return format adequately. Covers all parameters. Could mention rate limits or response size, but not critical for a read-only probe.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds some value by clarifying default model, free vs BYO pricing, and context purpose, but mostly repeats schema info.

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

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

Description uses specific verb 'probe' and resource 'LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model'. It clearly distinguishes from sibling tools by focusing on AI visibility scoring, not general 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?

States explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Does not provide negative guidance or alternatives, but the description is clear enough for an agent to infer when to use this tool over siblings.

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

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

Annotations already provide readOnly/openWorld/idempotent hints, and the description adds valuable behavioral context: 'one fast call', 'works on every tier', routing behavior, and stable citation URIs in the output. No contradictions with annotations exist.

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 typical but every sentence earns its place: it front-loads the main directive, then covers scope, behavior, examples, and alternatives in a logical structure. Only minor redundancy (e.g., restating 'START HERE' later) prevents a 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?

Given the tool's complexity as a router across thousands of sources, the description is remarkably complete. It explains the output format (structured answer, citations), speed expectations, tier availability, and when to escalate to grounded research or deep_research. No output schema exists, so the description fills that gap effectively.

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% since every parameter is described as an alias for 'question'. The description includes example queries, but they illustrate usage rather than adding new parameter-level information. Baseline of 3 is appropriate because schema does 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: it routes factual questions to 5,529 tools and returns structured answers with citations. It explicitly contrasts with siblings (ask_pipeworx_grounded, deep_research) and positions itself as the default entry point, making it unmistakable what this 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?

Usage guidance is explicit and actionable. It says 'PREFER OVER WEB SEARCH' for a wide range of factual queries, gives trigger phrases ('what is', 'look up', 'find'), and provides specific alternatives for grounded or multi-part research. This directly tells the agent when to use this tool versus siblings.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the tool's live state: 'candidate routing improvements enabled live whenever one is under test' and currently 'matches ask_pipeworx exactly.' It also clarifies 'Falls back to nothing — this IS a full working router,' preventing a misunderstanding that it's a partial fallback. No contradictions with annotations.

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

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

The description is four sentences and around 90 words, efficiently front-loading the core identity ('Beta version of ask_pipeworx'). Each sentence adds distinct value—definition, current state, usage, and fallback clarification—without obvious fluff. Slightly longer than strictly needed but well-structured.

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

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

Given the simple single-required-parameter schema and rich annotations, the description covers the essential context: what the tool is (beta router), its current behavior (matches stable router), when to use it, and that it returns the same shape as ask_pipeworx. It relies on the sibling description for full details, but that is acceptable because it explicitly says 'identical' to ask_pipeworx.

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 description does not add any parameter-level details, but the input schema already covers all six parameters with full descriptions and explains the aliases for 'question.' With 100% schema coverage, the baseline is 3, and there is no extra value from the description to raise it further.

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

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

The description clearly states this is a 'Beta version of ask_pipeworx' with 'identical universal router' and same tools/arguments/response shape, differentiating it from the stable ask_pipeworx by its experimental routing candidates. The verb 'ask' is implied and the resource is well-defined, making the purpose unambiguous and distinct from siblings.

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

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

Provides explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells when to use it and references the stable sibling, but it does not list explicit scenarios where it should not be used, so it stops short of a full when/when-not prescription.

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 the grounding behavior, the exact return structure including refusal reasons, the additional LLM call cost, and the strict reliance on tool result content. This goes well beyond the annotations (readOnlyHint, idempotentHint) by adding important operational details.

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

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

The description is well-structured, starting with a one-line summary, then explaining the mechanism, return formats, use cases, and cost tradeoff. Every sentence carries unique information without redundancy, making it dense yet readable.

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

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

Even though there is no output schema, the description completely specifies the success and refusal return structures, including all refusal reason codes. It also covers the cost implication and comparison to the sibling tool, making the description self-sufficient for a complex 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 provides 100% coverage with all six parameters described as aliases for the natural-language question. The description mentions 'fills arguments' but adds no parameter-level detail beyond what the schema states, so the baseline of 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 explicitly identifies the tool as a hallucination-resistant answer mode, distinct from ask_pipeworx, and clearly states the routing and extraction behavior. It uses specific verbs like 'EXTRACTS' and defines the resource scope, making it easy to distinguish from sibling tools.

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

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

Provides explicit guidance on when to use the tool ('high-stakes reads', 'quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It names the alternative tool directly, giving clear decision criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: low-confidence resolution short-circuits, closed markets return a status, wide spreads carry a tradeability note, resolution-rule risks are parsed, and the resolver contract is explained. No contradictions with annotations.

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

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

The description is very long (nearly 1500 characters) and includes many detailed examples and edge cases. While it is well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose, it could be more concise by reducing redundancy (e.g., extensive fan-out examples). It errs on the side of completeness over brevity.

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

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

No output schema is provided, so the description must fully explain return values. It covers the resolver contract, parent event extractor, news fields, safety behaviors, wide spread handling, and resolution-rule risk. All essential behaviors and edge cases are documented, making the description complete for a complex data-fetching 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 description coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for the 'market' parameter (slug, URL, question text) and clarifying the behavior of 'depth' and 'include_raw' parameters. This goes beyond the schema's own descriptions, justifying a higher 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 that the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies the inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). Use cases are explicitly listed: 'should I bet on X', 'what does the data say about Y', etc. No sibling differentiation is needed because the description is self-contained and 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 provides explicit use cases ('Use for "should I bet on X"...') and includes extensive fan-out examples for different bet types. However, it does not explicitly mention when not to use this tool or suggest alternative sibling tools (e.g., polymarket_arbitrage, polymarket_edges). The guidance is clear but lacks 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 indicate read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context: data sources (SEC EDGAR for companies, FAERS/FDA/clinicaltrials for drugs), handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs. This goes well 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 single, well-structured paragraph that front-loads trigger phrases. Every sentence adds value (trigger phrases, usage preference, data sources, sorting, output features). No redundancy or fluff.

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

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

For a comparison tool with only 2 parameters and no output schema, the description covers input format (tickers/CIKs for companies, drug names), data sources, sorting behavior, and output includes citation URIs. This equips the agent with sufficient context to invoke the tool correctly.

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

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

Schema coverage is 100% and schema already describes type and values with enums and constraints. However, the description enriches parameter understanding by specifying data fields pulled (revenue, net income, etc. for companies; adverse-event counts, approval counts, trials for drugs). This adds meaningful context beyond the schema's basic descriptions.

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

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

The description clearly states it performs side-by-side comparisons of 2-5 companies or drugs, with specific trigger phrases like 'compare X and Y' and 'which is bigger'. It distinguishes itself from sibling tools like entity_profile, which handles single entities, and sequential 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides trigger phrases and makes clear when to use this tool, effectively guiding the agent to choose it over 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?

Goes far beyond the annotations by detailing the decomposition into facets, parallel routing to 5,529 tools, the exact structure of the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] that are never invented, contradictions[] for standard/thorough depths, second-hop recovery behavior, semantic excerpting, latency expectations, and account/auth requirements. No contradiction with the readOnly/openWorld/idempotent/destructive 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 carries critical information, and it is front-loaded with account requirements, core purpose, and sibling alternatives. While it could be trimmed slightly (e.g., the citation_uri mechanics are quite detailed), the density of valuable guidance justifies the length for such a complex 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?

With no output schema, the description fully compensates by describing the return payload in detail: findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop field, and citation_uri. It also covers account tiers, latency, and tool behavior, making it complete for reliable invocation and response interpretation.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds practical meaning beyond the schema by giving example questions ('compare X and Y's regulatory + financial exposure'), clarifying that 'decomposition is the point,' and linking depth choices to paid plans and latency expectations, which enriches the agent's understanding of how to pick values.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and emphasizes 'this is NOT open-web search.' It distinguishes itself from sibling tools like ask_pipeworx by framing itself as best for broad, multi-part questions rather than single lookups, and explicitly contrasts with open-web/search tools.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also covers account prerequisites and the alternative to use when not signed in, making the decision boundary very 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 indicate readOnlyHint, idempotentHint, non-destructive. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations and is not contradicted.

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 primary purpose and use case, then lists domains. It is relatively concise for the amount of information conveyed, though the domain list could be trimmed. Overall good structure.

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 full parameter schema coverage, appropriate annotations, and clear description of output (names, descriptions, schemas ready to call), the description is complete. No output schema is needed because the description explains what to expect. Tool complexity is moderate and requirements are fully addressed.

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

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

Schema has 100% coverage with aliases and examples. The description mentions 'top-N' implying the limit parameter but does not add new meaning beyond the schema's existing descriptions. Baseline of 3 is appropriate as schema handles parameter semantics well.

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

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

The description explicitly states the tool finds tools by describing data or task, lists many specific domains (SEC filings, FDA drugs, etc.), and distinguishes itself from siblings as a discovery tool to browse available tools, which is unique among the sibling 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 clearly says 'Call this FIRST when you have many tools available and want to see the option set', giving explicit when-to-use guidance. It also implies usage via listing tasks like 'browse, search, look up, or discover'. It does not provide explicit when-not alternatives 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?

The description discloses internal behavior by listing all data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and specific return fields (cik, filings with URIs, fundamentals sorted, patents with sunset note, news fallback). Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral context beyond that.

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

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

The description is dense and informative, front-loading with example queries. Every sentence is valuable, though it could benefit from structural organization (e.g., bullet points or sections) to 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?

Given the tool's complexity (multiple sources, rich response), the description covers all major aspects: what inputs are accepted, what data sources are queried, and what fields are returned. It lacks mention of error handling or optional parameters but is sufficiently complete for an agent to understand the tool's capabilities.

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

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

Schema coverage is 100%, but the description adds critical context: type is limited to 'company' for now, and value accepts ticker or zero-padded CIK but not names. This clarifies parameter usage beyond the schema's enum and 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 opens with realistic user queries ('Tell me about X', 'research Acme') and explicitly states it provides a full cross-source profile of US public companies. It distinguishes itself from sibling tools like resolve_entity and compare_entities by noting when to prefer it and what it covers.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies that names are not supported and that resolve_entity should be used first if only a name is available, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true; description adds context about clearing sensitive data and pairing, but 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?

Two sentences, front-loaded with purpose, 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?

No output schema but appropriate for a delete operation; covers purpose, usage, and sibling pairing sufficiently.

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

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

Schema covers 100% of parameters with description 'Memory key to delete'; description does not add extra detail beyond the schema.

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

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

Description explicitly states 'Delete a previously stored memory by key' with a clear verb and resource, distinguishing it from siblings like 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and suggests pairing with 'remember' and 'recall'.

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

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

Describes the process: fetches page, extracts title/description/key links, emits standard markdown. Annotations declare idempotent and read-only, and description confirms non-destructive behavior. Adds context beyond annotations 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?

Four concise sentences, first sentence states purpose, subsequent sentences add use cases and output format. No redundant or irrelevant 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?

Given no output schema, the description fully explains the output as a single text blob in standard llms.txt format. Two parameters are well-documented in schema, and the description covers all needed behavioral 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 coverage is 100%, so the description doesn't need to add parameter details. It does not elaborate on 'max_links' default or format beyond the schema, which is acceptable but not value-added.

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

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

Clearly states it generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt'. Distinguishes from siblings by focusing on a specific output format for AI crawlers.

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

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

Explicitly lists three use cases: indexing client sites, drafting for own projects, auditing competitors. Lacks explicit when-not-to-use or alternative tools, but the use cases are clear and cover major scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds value by listing specific return fields (id, type, etc.) and indicating that active subscriptions are returned by default, with an optional include_inactive parameter. 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 extremely concise: two sentences that efficiently convey purpose, return fields, and usage guidance. Every sentence earns its place 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?

Despite lacking an output schema, the description fully compensates by enumerating return fields. It covers default behavior, optional parameter, and usage context. Combined with annotations, this is complete for a simple read-only list tool.

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

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

Schema coverage is 100% for the single parameter (include_inactive), and its schema description is already clear. The tool description does not add any new semantic information about the parameter beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions' which is a specific verb-resource combination. It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing rather than creating or deleting subscriptions.

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

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

The description provides 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 it, though it does not explicitly mention alternatives like 'subscribe' or 'unsubscribe'.

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

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

With all annotations set to false, the description carries the full burden of behavioral disclosure. It clearly explains the claim_token workflow for follow-up reads, rate limits (5 per day), no tool-call quota impact, and how feedback influences the roadmap. No contradictions with annotations are present.

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

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

The description is long but well-structured, starting with the core purpose and then expanding into usage, exclusions, and operational details. Each sentence earns its place, though the overall length could be trimmed slightly without losing value. The front-loading ensures the essential purpose is immediately clear.

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

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

Despite having no output schema, the description explicitly explains the return behavior (claim_token) and the follow-up read mechanism. It covers the tool's scope, usage rules, and operational constraints (rate limit, quota), making it sufficiently complete for a feedback submission tool with optional parameters.

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

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

The input schema already provides 100% coverage of parameter descriptions, so the baseline is 3. The description adds meaningful context by elaborating the claim_token usage (pass it back later) and by advising users to describe issues in terms of Pipeworx tools/packs, which enriches the 'message' and 'context' semantics beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('Tell the Pipeworx team') and a resource ('something is broken, missing, or needs to exist'). It enumerates distinct feedback types (bug, feature/data_gap, praise) and differentiates itself from siblings by being the sole feedback channel for Pipeworx tools.

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

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

The description explicitly states when to use the tool (for bugs, feature/data_gap, praise) and when not to use it, directing users to file issues for non-Pipeworx MCP servers elsewhere. It also offers practical guidance on what to include and avoid in the message, making the usage criteria 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 confirm readOnly, idempotent, non-destructive. Description adds details: derived from CF analytics-engine, no PII, caching window (5min-1h). This 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?

Concise (5 lines), front-loaded purpose, bulleted use cases, no fluff. Every sentence adds value.

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

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

For a simple tool with 1 optional param, full annotations, no output schema, the description explains what is returned (top tools, packs, volume), data source, and caching. Complete.

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

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

Schema covers window with enum and description (100% coverage). Description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

The description states 'Returns the top tools, top packs, and total call volume over a recent window' with specific timeframes, clearly distinguishing it from sibling tools like discover_tools.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing use case alignment). Does not mention when not to use or alternatives, but the guidance is sufficient.

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 extensive behavioral details beyond the annotations: the scanning process, monotonicity checks, partition-sum checks, fill check against CLOB depth, semantic anchor constraints (Jaccard similarity), and partition filter (placeholder slugs). Annotations already indicate read-only and idempotent behavior, and the description reinforces this 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 thorough but somewhat verbose. It is well-structured with clear sections for each mode and additional details, but could be slightly more concise without losing key information. Every sentence adds value, but the length may slow down parsing.

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 lack of an output schema, the description provides a comprehensive overview of the response structure (opportunities[], partition_check fields, fill check details). It also explains edge cases (semantic anchor, partition filter, thin legs) and directs users to a related tool for custom sizing. No critical information 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?

While the input schema already covers both parameters (event, topic) with descriptions, the tool's description adds substantial meaning: it explains the modes, provides example slugs ('fed-decision-may-2026'), clarifies that full URLs are accepted, and describes the cross-event scanning logic. This goes well beyond the schema's basic definitions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It also outlines three distinct modes (no args, event, topic) and their specific use cases, effectively distinguishing itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...' It recommends event mode for specific markets, explains that cross-event mode catches patterns missed by single-event mode, and directs users to polymarket_fill_risk for custom sizing. This clearly differentiates usage scenarios.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: caching policy, internal model families, edge calculation details, diagnostics, and caveats like Fed bets — all 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 long but well-structured with clearly separated sections and front-loaded purpose. Every sentence adds value, though it could be slightly more concise given 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?

Given the tool's complexity (9 parameters, no output schema, multiple model families), the description is exceptionally thorough: covers segments, edge metrics, diagnostics, caching, and practical usage guidance. Leaves no important 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?

All 9 parameters have descriptions in the input schema (100% coverage). The tool description provides overarching context but does not add significant new details for parameters beyond what the schema already provides.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It is specific verb+resource, distinguishing from siblings.

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

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

The description provides clear context on when to use ('discover opportunities without paging hundreds of markets') but does not explicitly compare or exclude alternatives among siblings.

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

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

Beyond annotations, the description details snapshot mechanics (cache-miss triggers), gaps meaning no scan, limitations (60-day TTL, daily closes), and response structure (tracked, expired, snapshot_dates). 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 information-dense but well-organized: purpose, args, response fields, limitations. Slight redundancy could be trimmed, but every part adds value.

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

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

For a tool with no output schema, the description fully explains the response fields, edge cases (gaps, TTL), and limitations. No critical information missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds default values, clamp ranges, and interprets 'window' as snapshot family, providing meaning beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry. It uses a specific verb (answers) and resource (edge snapshots), and distinguishes from sibling tools like polymarket_edges by emphasizing historical context.

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 context on when to use (to assess edge history and decay) and implies alternatives indirectly via sibling tool names. Explicit when-not-to-use guidance could be stronger, but the narrative makes it clear this is for historical analysis.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details behavior: walking the ladder, returning specific fields, explaining basket mode logic, and warning about forced directional risk. 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?

Structured with clear sections (SINGLE-MARKET, BASKET) and front-loaded key use case. Though dense, every sentence adds value. Slightly longer than necessary but remains effective.

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

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

Given no output schema, the description comprehensively lists return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, forced_directional_risk). Explains logic and risks, making it fully self-contained.

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

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

Schema coverage is 100%, yet the description adds meaning: defaults for side and size_usd, interpretation of size_usd as max spend or target proceeds for single-market, and settlement notional for basket. Explains auto-derivation of side for basket mode.

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 defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', with specific modes for single-market and basket. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying its role as a pre-check.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why and when not to use (small trades under $500), and the risks of partial fills.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds rich behavioral transparency: explains the two modes, compatibility_warning fields, temporal alignment, skipped types, and when output is meaningless. No contradictions with annotations.

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

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

The description is lengthy but well-structured with clear sections and front-loaded core purpose. Every sentence adds value, though minor tightening could be possible. It earns its length given tool 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?

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal alignment). It covers edge cases and provides comprehensive context for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so parameters are described. The description adds value by explaining the two modes, listing the predefined topics, and describing how explicit parameters override the topic mode. This goes beyond the bare schema.

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

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

The description clearly identifies the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling Polymarket-only tools like polymarket_arbitrage. It specifies the verb (computes spread) and the resource (two venues).

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

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

The description provides context on when to use the tool (e.g., two modes) and warns that pre-mapped topics often return compatibility warnings. However, it does not explicitly exclude alternatives like polymarket_arbitrage, leaving some ambiguity for the agent.

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

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

Annotations declare readOnly=true, idempotent=true, destructive=false. Description adds value by stating scoping to identifier (IP, key hash, account ID) and pairing with remember/forget. No contradictions.

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

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

Two concise sentences. First sentence states core action, second provides usage context and examples. No wasted words.

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

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

Given one optional parameter, annotations covering all relevant hints, and no output schema, the description is complete. It explains purpose, usage, scoping, and relationships to sibling tools.

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

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

Schema already has 100% coverage with description for 'key'. Description reinforces the 'omit to list all keys' behavior, but adds little beyond 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?

Description clearly states verb+resource: 'Retrieve a value... or list all saved keys'. Distinguishes from siblings (remember, forget) by explicitly mentioning them. Examples illustrate real use cases.

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

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

Describes when to use: to look up context stored earlier. Provides examples (ticker, address, notes) and mentions scoping. Doesn't explicitly say when not to use, but sibling tools cover alternatives.

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

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

Annotations already cover read-only and idempotent hints. Description adds behavioral context by explaining the 'mark_read' side effect and that polling works fine. No contradiction 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?

Very concise: three sentences front-loaded with the main action and purpose, then details on return values, filtering, and an alternative. No unnecessary words.

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

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

Given no output schema, description effectively explains return fields (source, citation_uri, payload), filtering options, mark_read behavior, and even provides an alternative endpoint. Covers all aspects of a simple list tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing example values for 'type' and 'since', and explaining the behavior of 'mark_read' beyond the schema descriptions.

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

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

Description clearly states verb ('pull fired events') and resource ('alerts from subscription feed'). It distinguishes itself from sibling tools like 'list_subscriptions' by focusing on events rather than subscriptions.

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

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

Description provides clear context for when to use (get recent alerts) but does not explicitly exclude alternatives or mention when not to use. It offers an alternative access method (URL) but no comparison to other tools.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. Description adds details about parallel call execution, source fallback, and soft-fail for USPTO, providing valuable context beyond annotations.

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

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

Description is moderately detailed but every sentence adds value. Front-loaded with typical usage scenarios. Could be slightly more concise but effective.

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

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

Even without output schema, description specifies return structure (changes[] grouped by source, total_changes, citation URIs) and notes limitations (USPTO soft-fail). Sufficient for agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds examples for since (ISO date or relative shorthand) and clarifies value accepts ticker or CIK, enhancing usability.

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

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

The description clearly states the tool provides a change feed for companies using multiple sources (SEC, GDELT/GNews, USPTO). It also distinguishes from entity_profile, which provides static profiles.

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 concrete examples of queries ('What's new with X') and explicitly says when to use entity_profile instead. Also explains fallback behavior between GDELT and GNews.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds 'fetch full details' which is implied by the name and title, offering no additional behavioral insight beyond annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. Every part earns its place by defining the tool's core purpose and parameter origin.

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 tool with two parameters and rich annotations, the description is adequate but could specify what 'full details' includes, especially 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?

Schema coverage is 100%, so the schema already documents both parameters. The description mentions the id format and that _apiKey is auto-injected, which adds minimal value over the schema definitions.

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

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

The description clearly states the verb 'Fetch' and resource 'full details for one Europeana item by id', specifying the input as a Europeana record id from search. This effectively distinguishes it from sibling tools like search that list items.

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 context by explaining where to get the id ('from search'), but does not specify when not to use this tool or mention alternative tools for similar tasks.

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 context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already indicate idempotentHint=true and non-destructive, so the description complements 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 efficient and front-loaded with the core purpose. Each sentence adds value (scope, usage, persistence, pairing). Slightly verbose but not unnecessary.

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 store with no output schema, the description covers purpose, usage, persistence, and pairing. It is complete enough for an agent to understand and invoke the tool correctly.

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

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

Schema covers 100% with descriptions. The description adds examples for key (e.g., 'subject_property', 'target_ticker') and clarifies value can be any text. This enriches the schema without redundancy.

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: 'Save data the agent will need to reuse later.' It specifies the verb (save), resource (data), and scope (across sessions). It distinguishes from sibling tools like 'recall' and 'forget' by naming them as counterparts.

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

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

Explicit guidance on when to use: 'Use when you discover something worth carrying forward.' It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' This helps the agent decide correctly.

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 non-destructive, but the description goes beyond by explaining the tool cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, labels each identifier with its source, and explicitly lists unresolved identifiers under 'unresolved'. This rich behavioral context exceeds annotation coverage.

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 typical but well-structured with a clear opening, supported-type breakdown, and explicit degradation note. Each sentence contributes unique information, such as the list of identifiers, source labeling, and replacement of manual lookups. It is front-loaded with examples and organized for quick scanning.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns: CIK, ticker, company_name, LEI, ownership relations, FIGI, and drug identifiers (RxCUI, ingredient, brand). It also covers edge cases like unresolved identifiers and graceful degradation, making the tool's behavior predictable and complete for an AI 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?

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by providing concrete input examples (AAPL, 0000320193, 'ozempic') and clarifying that the value parameter accepts ticker, CIK, or name for company, and brand or generic name for drug. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with specific verbs and examples ('ticker', 'CIK', 'LEI', etc.). It distinguishes its purpose from sibling tools by emphasizing it maps names to IDs required by other tools, and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details the two supported entity types (company, drug) and the accepted input formats for each, effectively telling the agent when to invoke this tool versus alternatives like search or entity_profile.

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

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

The description explains the internal process (probes each entity with ai_visibility_check), the return format (ranked list with score, confidence, signal density), and mentions optional API key usage for Anthropic. Annotations already indicate read-only, idempotent, and non-destructive behavior, which the description complements 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 paragraph of three sentences, efficient and front-loaded with the main action. No redundant words, but could be slightly more structured (e.g., separating usage note from return format). Still very 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?

The description explains the return value (ranked list with score, confidence, signal density) in the absence of an output schema. It also specifies entity count range (2-8) and use case. For a scanning tool with rich annotations, this 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 has 100% description coverage, but the tool description adds useful context beyond schema: first entity is treated as 'subject', the context parameter disambiguates common names, and models defaults to workers-ai. This extra meaning helps the agent understand parameter intent.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking by score. This is specific and distinguishes it from sibling tools like compare_entities or ai_visibility_check.

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 an example question. It implies when to use (multiple entities) but does not explicitly contrast with single-entity tools 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?

Describes graceful degradation on partial failures and a 5-30s delay for new bundlephobia measurements, which adds value beyond the annotations that indicate read-only and idempotent behavior. 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 informative but slightly long at 4-5 sentences. It is well-structured with purpose first, then usage, return details, scope, and failure behavior, so it earns 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?

No output schema is provided, but the description enumerates return fields, explains partial failure behavior, and scopes the tool appropriately. Minor missing details about advisory content, but overall adequate.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description repeats the scoped package acceptance but does not add new meaning beyond the schema, justifying a baseline score of 3.

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

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

The description clearly defines the tool as a composite check for npm packages, covering license, security, and size metrics. It distinguishes from sibling tools by specifying NPM-only scope and directing other ecosystems to alternative tools.

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

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

Explicitly states when to use ('is X safe/popular/small' or 'what does adding lodash cost me') and notes that for PyPI/Maven/Cargo/Go, the user should use deps.dev:version directly, providing 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?

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) indicate safe, read-only behavior. The description adds context by listing typical return fields, complementing the annotations 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 concise sentence that packs essential information: target collection, action, keyword, and return fields. No unnecessary words.

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

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

Given the tool's simplicity and the presence of annotations and full schema, the description is adequate. It explains the purpose and output, though it could mention pagination or limit defaults.

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

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

Schema coverage is 100% with all parameters documented. The description adds minimal extra meaning beyond the schema; it sets the overall context but does not elaborate on individual parameters.

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

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

The description clearly states the tool searches the Europeana collection by keyword and lists the returned fields (ids, titles, etc.). This is specific and unambiguous, distinguishing it from the listed siblings which are unrelated.

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

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

No guidance on when to use this tool vs alternatives. The description only states what it does, without mentioning when not to use it or contrasting with sibling tools.

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

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

Annotations already declare safe read-only behavior. The description adds rich behavioral context: embedding model (BGE-base-en), windowing (500-char overlapping), character offsets, similarity scores, truncation with flag, and 200K char cap. This goes well 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?

Two sentences, no wasted words. The first sentence immediately conveys the core purpose. Every clause adds distinct information (what it does, when to use, how it works, limitations).

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

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

Despite lacking an output schema, the description explains the return format (passages with character offsets and similarity scores). It covers embedding details, truncation, pairing with another tool, and usage guidance. This is fully adequate 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%, so baseline is 3. The description adds value by clarifying the 'text' parameter's max length, providing example queries for 'query', and specifying the range for 'limit'. This enhancement 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 uses a specific verb ('search inside') and resource ('a fetched record'), and distinguishes from sibling tools like 'ask_pipeworx_grounded' by explaining they pair together. Examples of use cases (SEC 10-K, article) 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and describes how it pairs with another tool. However, it does not explicitly state when not to use it or list alternatives beyond the one mentioned.

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

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

Adds significant behavioral context beyond annotations: OAuth requirement, subscription type details, delivery channel constraints (SMS verification and cap, webhook signing and auto-disable). 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?

Well-structured with purpose first, then requirements, types, delivery channels. Slightly long but each sentence adds necessary detail. Could trim redundant phrasing but remains clear.

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

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

Covers most aspects: return value, types, parameters, delivery constraints. No output schema but describes returned subscription id. Missing is any mention of output format or behavior for invalid inputs, but adequate given complexity.

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

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

Schema coverage is 100% with descriptions, but the description enriches each parameter with concrete examples (e.g., sec_8k items, delivery channels with verification details). Adds value beyond the schema.

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

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

Clearly states 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id' — specific verb and resource. Distinguishes from siblings like unsubscribe and list_subscriptions by focusing on creation.

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

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

Explicitly mentions requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. Provides context for when to use but lacks explicit when-not-to-use or alternative tools beyond the sibling list.

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. Description adds that it returns example questions drawn from the live catalog and supports optional topic focus, going beyond annotations.

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

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

Description is slightly verbose but well-structured with common queries front-loaded. 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?

Simple tool with one optional parameter and no output schema. Description fully covers input behavior and return content, making it complete for agent use.

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

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

Schema coverage is 100% but description adds examples of topic values (finance, pharma, etc.) and explains behavior with/without argument, significantly enriching meaning.

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

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

Description clearly states it returns category-bucketed example questions with exact tool+argument shapes. It is the onboarding entry point, distinct from sibling tools like ask_pipeworx or 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and 'to learn how to call meta-tools'. No ambiguity on when or why 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?

The description reveals that the row is deactivated (not deleted) and historical events remain accessible via recent_alerts, adding value beyond annotations (idempotentHint, destructiveHint).

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

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

Two sentences with no superfluous words. Information is front-loaded and every sentence contributes 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?

The description covers purpose, ownership, and side effects. It lacks error handling or idempotency details (though idempotency is in annotations), but is adequate for a simple 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 already describes the 'id' parameter as a uuid returned by subscribe. The tool description adds no new information about the parameter beyond stating cancellation 'by id', so it meets baseline but adds little.

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

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

The description clearly specifies the action ('Cancel a subscription by id') and distinguishes the tool from siblings like 'subscribe' and 'list_subscriptions' by stating the operation and ownership enforcement.

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: you must own the subscription to cancel it. However, it does not explicitly state when to use this tool versus alternatives, or mention idempotency.

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 significant behavioral detail beyond the annotations: it explains the possible verdicts, clarifies that 'could_not_verify' means the check failed and must not be treated as evidence, and defines 'unsupported'. These are non-obvious semantics that the readOnly/openWorld/idempotent hints alone do not convey.

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

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

The description is dense but well-structured, starting with natural-language trigger phrases and then layering in usage, routing, return values, and caller warnings. While it is longer than a typical description, every sentence earns its place given the complexity of the tool's behavior.

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 burden of explaining return values and edge cases. It thoroughly covers the verdict set, meaning of 'could_not_verify' vs. 'unsupported', and the consolidation of multiple pipeline steps. This is complete for a tool of this complexity.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds minor context by mentioning 'exact percent-delta math' for financial claims, but the schema already thoroughly documents both 'claim' and 'tolerance_pct' with examples and defaults. The description does not significantly compensate beyond the schema.

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

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

The description clearly identifies the tool as a natural-language claim verification service with a specific verb ('validate') and resource ('claim'). It distinguishes itself from sibling search/research tools by focusing on fact-checking and by describing the financial-claim fast path vs. the grounded fallback pipeline.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and distinguishes between company-financial and other claims. It does not explicitly mention sibling alternatives or when not to use it, but the usage context is strong.

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