Zenodo

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: default model is free, Anthropic requires BYO key, and returns per-model plus combined view. 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 two sentences plus a short explanation—every sentence adds value. It is front-loaded with the main action and contains 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?

For a tool with 4 parameters (1 required), no output schema, and no nested objects, the description explains the return format and use cases adequately. It is complete given the 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 description coverage is 100%, so each parameter already has a description. The description adds extra context (e.g., _apiKey needed only if anthropic is in models) but 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 uses specific verbs ('probe', 'score') and clearly identifies the resource (LLMs) and output (visibility score 0-100). It distinguishes itself from siblings by focusing on AI visibility scoring across models, not general search or research.

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

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

The description states explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not, however, provide explicit exclusions or mention alternative tools among the 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context by revealing that the tool routes to many other tools, fills arguments on behalf of the user, and returns stable pipeworx:// citation URIs. This makes the tool's plumbing transparent in a way the annotations alone do not. There is no contradiction with the annotations.

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

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

The description is long but front-loaded: it starts with the most important directive, follows with supported categories, examples, and alternative-tool routing. Each sentence carries functional weight and the examples are specific. Slight redundancy exists between the opening and closing directives, but overall the structure aids an agent's decision-making efficiently.

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 that there is no output schema, the description adequately describes what the return will look like: a structured answer with pipeworx:// citation URIs. It also covers what kinds of questions fit, gives concrete examples, and routes to siblings. It does not cover edge cases like ambiguous questions or unavailable sources, but those are not essential for a tool of this type under the given annotations.

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

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

The input schema already documents 100% of parameters, all as aliases for a natural-language question string. The description adds example queries and domain context, which is helpful, but it does not add essential meaning to the parameter semantics. With this high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states that this tool routes factual questions to one of 5,596 tools across 1,465 verified sources and returns structured answers with pipeworx:// citation URIs. It names the specific function—answer factual/current/historical questions—while distinguishing itself from sibling tools like deep_research or ask_pipeworx_grounded. The phrase 'PREFER OVER WEB SEARCH' leaves no doubt about this tool's role.

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 tool description explicitly tells agents when to use it: whenever the user asks 'what is', 'look up', 'find', 'get the latest', 'how much', 'current', or any factual question, even if web search could answer it. It also explicitly names alternatives and their scenarios: deep_research for multi-source reports, ask_pipeworx_grounded for unambiguous citation-driven answers, ask_pipeworx_beta for experimental features, and bet_research for arbitration/prediction contexts. This is exemplary when-to-use/when-not-to-use guidance.

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

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

The description adds important context beyond the annotations: no candidate routing improvement is currently active, it currently matches ask_pipeworx exactly, it is a full working router with no fallback, and its results are compared against the stable router. These behavioral and current-state disclosures are meaningful and not encoded in annotations.

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

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

Every sentence earns its place: beta status, current candidate state, relationship to the stable router, and the absence of fallback. The phrase 'Falls back to nothing — this IS a full working router' is front-loaded, unambiguous, and prevents a major misuse.

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

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

The description is complete for an agent to invoke the tool correctly. It explains functional scope, current exact behavior, argument and response equivalence with ask_pipeworx, and the safe/read-only nature is already covered by annotations. Nothing needed to call or interpret this tool is missing.

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

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

The input schema already has 100% coverage for the required 'question' parameter and its aliases, each described clearly. The description says 'same arguments' but adds no independent meaning beyond what the schema provides, so the baseline of 3 fits.

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 beta version of ask_pipeworx: a universal router with the same tool set, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by positioning it as the experimental edge of the same behavior.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives a clear condition for choosing this tool over the stable ask_pipeworx. It does not explicitly enumerate when NOT to use it or contrast it with ask_pipeworx_grounded, so it stops short of a full when/when-not matrix.

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

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

The annotations already cover read-only, idempotent, not destructive. The description adds substantial behavior beyond that: extraction-only grounding, refusal semantics, refusal_reason enumerations, return structure, and the extra cost. There is 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?

Front-loaded with the core behavior, then method, then output/refusal contract, then usage guidance, then cost trade-off. Each sentence carries a distinct and necessary piece of information with no filler.

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

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

Despite no output schema, the description fully describes the success return object and every explicit refusal_reason value, and ties the tool's behavior to representative high-stakes use cases. An agent can correctly call the tool and interpret both success and failure outcomes.

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

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

Schema description coverage is 100%; the schema details the question parameter and all accepted aliases. The description itself says nothing about parameters that adds meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly and specifically defines the tool as a grounded, hallucination-resistant answer mode: it routes, fetches data, and extracts the answer only from the tool result. It distinguishes itself from the sibling ask_pipeworx and ask_pipeworx_beta by naming the routing overlap and the grounded/refusal behavior.

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

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

Explicit when to use: 'anytime an answer will be quoted, cited, or acted on' and gives concrete domains (financial, legal, medical, public statements). It also explicitly says to prefer ask_pipeworx for casual lookups, naming the alternative and the trade-off (extra LLM call).

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 annotations by detailing market resolution, classification, fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback fields, safety for low-confidence/closed markets, wide spread handling, and resolution-rule 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?

Long but well-structured with bold headers and sections. Front-loads the core purpose. Every detail seems justified given tool complexity, but could be slightly trimmed for faster 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?

Exceptionally complete for a tool with 3 parameters, no output schema, and high complexity. Covers response shapes, edge cases, safety, and resolution risks. Leaves little ambiguity about what the tool returns and how it behaves.

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

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

Adds significant meaning beyond the schema: explains 'market' accepts slug/URL/question text with examples, describes 'depth' quick vs thorough, and elaborates on 'include_raw' trade-offs. Schema coverage is 100%, so baseline is 3, but description elevates it.

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

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

Description clearly states it researches a Polymarket bet by pulling relevant Pipeworx data. Provides specific input types (slug, URL, question text) and distinguishes from sibling tools by focusing on comprehensive data fan-out for a single bet.

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

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

Explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). While it doesn't directly contrast with sibling tools, the detailed description implies when to use. Could be improved by specifying when to use alternatives like ask_pipeworx.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and side-effects. The description adds value by specifying the return format (community id, title, description, record count). It does not contradict annotations.

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

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

The description is a single, well-structured sentence that front-loads the tool's purpose and includes return information. No superfluous words.

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

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

Given the tool's simplicity, the presence of an output schema (reducing need to explain returns), and rich annotations, the description is mostly complete. It could mention pagination behavior or defaults, but overall it satisfies the minimum requirements.

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

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

The input schema has three parameters (page, size, query) with 0% schema description coverage. The description only explains 'query' as an optional keyword, leaving 'page' and 'size' unexplained. The description does not compensate adequately for the missing schema descriptions.

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

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

The description clearly states the tool lists or searches Zenodo communities with an optional keyword query, and specifies the returned fields (id, title, description, record count). This is a specific verb+resource combination that distinguishes it from sibling 'community_records', which likely deals with records within a community.

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

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

The description implies usage for searching/listening communities via keyword, but does not explicitly state when to use it versus alternatives like 'community_records'. It offers no exclusions or prerequisites, leaving the agent to infer context from 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns 'record metadata, DOIs, and file links' and mentions pagination via 'page' and 'size', which supplements the high 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?

Two sentences with no wasted words. The description front-loads the action and resource, then lists return contents. Highly concise.

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

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

Given the presence of an output schema (not shown but indicated by context), the description does not need to detail return values. It adequately explains the community scope, pagination, and what is returned (metadata, DOIs, file links). Complete for the tool's purpose.

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

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

The schema has 0% description coverage. The description explains the 'id' parameter as a 'slug id' with an example, adding meaning. However, 'page' and 'size' are not described, so the description only partially compensates for the lack of schema descriptions.

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

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

The description clearly specifies the action 'Fetch paginated records' and the resource 'Zenodo community by its slug id', with an example. It distinguishes from siblings like 'record' and 'record_files' by focusing on community-level records.

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

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

The description implies the use case (fetching all records in a community) but does not explicitly state when to use this tool versus alternatives like 'record' for a single record or 'record_files' for files. No exclusions are provided.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds valuable details: for 'company' type, it pulls specific financial metrics from SEC EDGAR/XBRL with correct off-calendar handling; for 'drug' type, it pulls FAERS, FDA approval counts, and trial counts. It also discloses sorting behavior and return format.

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

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

The description is relatively concise given the complexity, using bold for emphasis and clear separation of details. Every sentence adds value, though it could be slightly more streamlined.

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

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

Given no output schema, the description adequately explains return data (paired data with citation URIs) and sorting. It covers key behaviors for both entity types and provides sufficient context for correct invocation.

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

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

Input schema has 100% coverage with descriptions. The description adds examples and clarifications (e.g., 'for company: 2-5 tickers/CIKs') and explains the effect of each enum value. 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 the tool performs side-by-side comparison of 2-5 companies or drugs in a single call, with specific verb phrases like 'compare', 'vs', 'versus', 'rank'. It distinguishes between entity types and their data sources, and explicitly contrasts with 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?

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides a concrete efficiency gain ('Replaces 8–15 sequential lookups'). It gives context for when to use, though does not specify scenarios where this tool should not be used.

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?

Even with readOnlyHint/openWorldHint/idempotentHint annotations, the description adds rich behavioral detail: it returns gaps[] for unanswered facets and 'never invented' findings, describes hop-based iteration by depth level, explains citation_uri availability rules, contradicts `contradictions[]` behavior, semantic excerpting, and expected latency. This far exceeds the annotation burden.

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

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

The description is long but dense: every sentence contributes operational or selection value, and it is front-loaded with the account requirement and primary alternative. It could be tightened slightly, but it avoids filler and organizes complexity well across purpose, alternatives, depth behavior, outputs, and latency.

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 that there is no output schema, the description compensates thoroughly by describing the findings packet fields, citation format, gaps[]/contradictions[] semantics, hop fields, iteration behavior, and runtime expectations. The tool is complex, and the description provides enough for an agent to understand what happens before and after invocation.

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

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

Schema coverage is 100%, so the baseline is high. The description adds real value beyond the schema by linking depth values to concrete behavior: 'standard' adds gap-recovery hop and contradictions[], 'thorough' requires a paid plan and adds a full iterative lead-chasing pass, with expected latency ranges. This meaningfully enriches both 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 states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' that decomposes questions into facets and routes them across tools in parallel. It distinguishes itself clearly from open-web search ('this is NOT open-web search') and from the ask_pipeworx sibling tools by its breadth and structured-data focus.

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

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

The description gives explicit when-to-use guidance ('best for broad/multi-part questions over structured data') and explicit alternatives: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also flags account and paid-plan prerequisites, so an agent can route correctly before invoking.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns '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.' No contradictions.

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

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

Description is moderately sized, front-loaded with key verb 'Find tools...', and every sentence adds value. Could be slightly more concise, but overall well-structured and efficient.

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

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

Given 6 parameters, full schema coverage, no output schema, the description adequately explains the return value (top-N tools with names, descriptions, schemas, examples) and usage scenario. Complete for a discovery tool.

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

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

Schema description coverage is 100% (all 6 parameters described). The description provides example queries but does not add significant meaning beyond what the schema already states about aliases. Baseline 3 is appropriate.

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

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

The description clearly states it 'find[s] tools by describing the data or task,' lists many example domains (SEC filings, FDA drugs, etc.), and explains it returns top-N relevant tools with schemas ready to call. This distinguishes it from sibling tools like 'search' or 'deep_research' which are for data retrieval, not tool discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implies alternatives are the specific tools in the set.

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

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

The description goes beyond annotations by detailing the tool's behavior: it fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), specifies return fields, and discloses a soft-fail for patents. 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 relatively long but well-structured with a front-loaded trigger phrase list, followed by a breakdown of functionality. It efficiently packs information without unnecessary verbosity.

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

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

Given no output schema, the description compensates by listing return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and their sources. It also notes limitations and fallbacks, making it complete for the tool's complexity.

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

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

Schema coverage is 100% and parameter descriptions are already clear. The description adds value by providing concrete examples (e.g., 'AAPL', '0000320193') and reinforcing the limitation on names, but does not add deeper 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 purpose: providing a full cross-source profile of a US public company in one parallel call. It gives multiple example queries and explicitly distinguishes from chaining individual 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?

The description explicitly advises when to use this tool (holistic view) and when not (if only a name is provided, use resolve_entity first). It also recommends preferring this over chaining multiple single-pack lookups, providing clear 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 and idempotentHint=true, so the description's addition of 'clear sensitive data' and 'stale context' provides useful behavioral context beyond the technical hints. No contradictions found.

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

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

Two sentences with no wasted words. The main action is front-loaded in the first sentence, usage guidance in the second, and a brief reference to related tools. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and well-covered annotations, the description fully covers purpose, usage, and relationships. No gaps remain.

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

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

Input schema has 100% coverage for the single parameter 'key' with description 'Memory key to delete'. The tool description does not add additional parameter semantics beyond what the schema already provides, meeting the baseline for high schema coverage.

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

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

Description clearly specifies the verb 'Delete', the resource 'previously stored memory', and the method 'by key'. It leaves no ambiguity about the tool's function and distinguishes it from siblings by explicitly mentioning pairing with '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 guidance on when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also implies when not to use by pointing to alternative tools ('remember' and 'recall'), offering clear context for decision-making.

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 non-destructive. The description adds behavioral details: it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions. Could disclose more about error handling or size limits, but sufficient given 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 concise (two sentences plus a list), front-loaded with the action, and every sentence adds value. No redundancy.

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

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

For a tool with no output schema, the description adequately explains the output format (standard llms.txt markdown) and placement (site-root/llms.txt). Covers all essential aspects without gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minimal value beyond schema, such as 'production-ready' and 'standard format', but does not enhance understanding of parameters 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 the tool generates a production-ready llms.txt file for any URL, specifying the resource (llms.txt), action (generate), and purpose (AI crawling). It distinguishes from sibling tools by focusing on a specific output format and use case.

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

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

The description lists explicit use cases (client indexing, personal projects, auditing competitors), providing good context for when to use. However, it does not mention exclusions or when to use alternative tools from 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, idempotentHint, and destructiveHint=false. The description adds value by listing the exact return fields (id, type, params, etc.), which is 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, front-loaded with purpose. Every sentence adds value: first sentence states action and output, second gives usage context. No waste.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains return fields and provides usage context, which is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the parameter include_inactive is fully described in the schema. The description adds no additional meaning beyond this, so baseline score applies.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb (list) and resource (subscriptions), and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear when-to-use guidance and complements 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 are all false and convey little, so the description carries the behavioral burden. It discloses rate limiting (5 per identifier per day), account-free usage returning a claim_token, the ability to poll later for status, and the fact that it is free with no quota impact. This goes well beyond what the annotations state.

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

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

The description is front-loaded with purpose and usage criteria, then covers exclusions and behavioral details. It is longer than the average tool description, but every section adds operational value; only the roadmap-impact sentence is slightly extraneous. It earns a 4 rather than a 5 due to mild redundancy.

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

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

For a nuanced feedback tool with no output schema, this description covers return values (claim_token), follow-up mechanics, rate limits, auth (no account needed), scope restrictions, and per-type usage. It equips the agent with everything needed to decide and invoke correctly, making it complete for its complexity.

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

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

The input schema already describes all four parameters with detailed enum and field descriptions, so the baseline is 3. The description adds practical guidance on the message field (focus on Pipeworx tools/packs, don't paste the end-user's prompt) and demonstrates the claim_token usage pattern, enriching 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 first sentence clearly states the function: reporting feedback to the Pipeworx team. It lists concrete triggers (broken, missing, needs to exist) and differentiates from sibling tools by restricting scope to this Pipeworx connection's tools, making it distinct from tools like ask_pipeworx.

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

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

The description gives explicit when-to-use criteria for bug, feature/data_gap, and praise, and includes a clear exclusion rule: feedback for other MCP servers should be filed elsewhere. It also offers a heuristic for identifying Pipeworx tools, providing actionable guidance beyond just a general purpose.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds: derived from CF analytics-engine, no PII, cached 5min-1h. No contradiction.

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

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

Concise: three sentences covering purpose, use cases, and implementation. Front-loaded with main function.

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

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

Despite no output schema, description specifies output contents (top tools, packs, count), data source, caching, and privacy. Complete for a read-only aggregator.

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 enum and description. Description adds meaning about window: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clearly states it returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and resource 'trending' are specific. Differentiates from sibling tools that focus on search or retrieval.

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

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

Lists three explicit use cases: discovering hot data sources, confirming tool choice, seeing alignment. Does not explicitly state when not to use, but the use cases are clear and context-appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantial behavioral context: how scans work (monotonicity, partition sum), filters (Jaccard similarity, placeholder fraction), fill check details, and trade signals. 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 detailed but well-structured, starting with a clear summary then breaking into modes. It could be slightly more concise (e.g., the partition_check explanation is dense), but every sentence adds value. The structure facilitates 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 tool's complexity (multiple modes, filters, response format, fill check) and absence of output schema, the description is remarkably complete. It covers response structure, trade suggestions, when not to trade, and concrete examples. Sibling tools like polymarket_edges and polymarket_fill_risk are implicitly differentiated.

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

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

Schema coverage is 100% (both parameters described), so baseline is 3. The description adds significant meaning: explains event slugs, topic as seed question, no-args default to trending scan, and internal processing details. This enriches the agent's understanding beyond the schema.

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

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

The description explicitly states the tool's purpose: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It details three distinct modes (no args, event, topic) and distinguishes them clearly. The purpose is specific and differentiates from sibling tools like 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: no args for trending scan, event for specific market slug, topic for cross-event scanning. It also advises against trading when realizable_edge_pp ≤ 0, and references polymarket_fill_risk for custom sizing. This covers when, when not, and alternatives.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context: caching at KV level for 1 hour, model families, slippage and Kelly calculations, response structure including diagnostics, and edge computation details. 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 lengthy but well-structured with clear sections for model families, response structure, and tradeable-edge knobs. It front-loads the main purpose. Some internal details could be condensed, but the structure aids understanding.

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 9 parameters, no output schema, and complex edge computation logic, the description is very thorough. It explains the three response segments, diagnostics, caching, and parameter usage, providing everything an agent needs to understand and use the tool 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% with detailed schema descriptions for each parameter. The main description adds extra context like 'edge is evaluated NET of slippage' and explains the role of each knob in filtering, which goes beyond the schema. A score of 4 reflects this added value.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes from siblings by detailing three edge segments and tradeable-edge knobs.

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

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

The description gives explicit guidance on when to use the tool ('agents discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs for filtering. However, it does not explicitly state when not to use it or compare directly 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?

The description adds behavioral context beyond the annotations: it explains that decay numbers are from daily closes, not intraday, and that gaps in snapshots mean no scan occurred. It also details the response structure. Annotations already indicate readOnly and idempotent, and the description is consistent.

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

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

The description is concise and well-structured: it starts with the main purpose, then details the response fields, and ends with limitations. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description provides a thorough explanation of the response (tracked, expired, snapshot_dates) and covers limitations. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining 'days' as lookback (default 14, max 30) and 'window' as snapshot family with examples. It also clarifies the response structure, further aiding parameter understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on temporal analysis.

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

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

The description implies use when edge persistence history is needed, but does not explicitly state when to prefer this tool over alternatives or when not to use it. No sibling differentiation is provided, though the context of decay and persistence is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint = true; description adds detailed behavior: walks the ladder, returns specific fields, explains basket mode calculations, warns about partial fills converting arb to directional positions. No contradiction.

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

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

Long but dense; uses bolding and sections. Front-loads purpose. Every sentence adds value, though slightly verbose; could be marginally tighter without losing clarity.

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

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

No output schema, but description details all return fields for both modes (single and basket), including verdicts, capture ratio, thin legs, forced directional risk. Also covers edge cases and warnings. Highly complete.

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

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

Schema coverage is 100%, but description adds significant meaning: explains mutual exclusivity of market/event, side default in basket mode ('auto from partition sum'), size_usd interpretation as settlement notional in basket mode. Schema descriptions are adequate but description enriches 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 the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket/partition) and connects to sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains when not to use (thin books, partial fills convert arb to directional) and why (dominant loss mode).

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) already signal safety. Description adds depth: explains output structure (leg-by-leg prices, spread array, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and conditions for warnings. No contradiction.

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

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

Description is long (~250 words) but well-structured: purpose, modes, output, safety fields, caution. Every sentence adds value. For a complex tool, length is justified; not perfectly concise but organized.

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 compensates fully: explains output structure leg-by-leg, spread array, temporal alignment, skipped counters. With 3 parameters and rich annotations, description covers all essential 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 covers 100% of 3 parameters with descriptions. Description adds value: explains topic auto-mapping, override behavior of explicit tickers, and links to response behavior. Baseline 3 plus extra context justifies 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?

Clearly states cross-venue spread between Kalshi and Polymarket for same resolving question. Distinguishes from siblings like polymarket_arbitrage by focusing on two-venue comparison. Two explicit modes and response structure reinforce 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?

Provides explicit guidance: use when comparing pricing of same outcome across venues, avoid when compatibility_warning fires (non-equivalent bet shapes or unrelated events). Warns that real spreads are rarer than macro shortcuts. Details both modes and safety fields.

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, idempotent, non-destructive hints. The description adds useful behavioral details: scoping to identifier (anonymous IP, BYO key hash, account ID), and that omitting key lists all keys. 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?

Extremely concise: three sentences that front-load the main action, then add use cases, scoping, and pairing. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: function, use cases, scope, and relation to sibling tools. It is complete.

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

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

Schema coverage is 100% with the parameter description already explaining its behavior. The description reinforces but does not add significant new meaning beyond the schema, so baseline of 3 is appropriate.

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

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

Clearly states the verb 'Retrieve' and the resource 'a value previously saved via remember, or list all saved keys'. It distinguishes from siblings by explicitly pairing with 'remember' (save) and 'forget' (delete).

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

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

Provides clear context on when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing but doesn't explicitly state when not to use, though the context and sibling tools make it obvious.

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

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

Annotations already indicate a safe, read-only, idempotent tool. The description adds value by detailing the mark_read side effect (next call shows newer events) and confirming the same feed is available via a GET endpoint. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with no filler. It starts with the core purpose, then details return fields and filtering, and ends with a practical note about polling and an alternative endpoint. Every sentence earns its place.

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

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

The description covers return fields and key parameters (type, since, mark_read) but omits the 'unread_only' parameter entirely. It also does not explain behavior when no new alerts exist or error cases. For a tool with no output schema, these gaps reduce completeness.

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 meaning beyond the schema by explaining the effect of 'mark_read' (flags events read for subsequent calls) and noting that 'polls work fine,' which implies no rate concerns. This extra context earns a 4.

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

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

The description clearly states the tool pulls fired events from a subscription feed and lists return fields (source, citation_uri, payload). However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'recent_changes', so it loses the top score.

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

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

The description provides practical usage tips (filtering options, mark_read flag, polling suitability) and even an alternative HTTP endpoint. But it lacks explicit when-to-use or when-not-to-use guidance relative to sibling tools, limiting its decision support.

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, etc. Description adds valuable context: fans out to multiple sources, soft-fails for USPTO, fallback logic, and return format 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?

Description is relatively long but every sentence adds value. Front-loaded with examples. Could be slightly more concise 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 complexity and no output schema, description explains return format (changes[] grouped by source, total_changes, citation URIs). Covers all necessary aspects.

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 meaning: clarifies type only supports 'company', explains `since` format with examples, and `value` accepts ticker or CIK. Also recommends typical `since` value.

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

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

The description clearly states it returns a change feed for a company over a window, fanning out to multiple sources (SEC EDGAR, GDELT->GNews, USPTO). It distinguishes from sibling entity_profile for static profile.

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

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

Explicitly lists example queries like 'What's new with X' and instructs when to use entity_profile instead. Provides context on fallback behavior for GDELT->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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering key behavioral traits. The description adds only the 'Zenodo id' context, offering no additional behavioral details 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 extremely concise—just five words—yet conveys the essential purpose without any wasted text. It is efficiently front-loaded.

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

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

Given the presence of an output schema and rich annotations, the description is adequate for a simple tool with one parameter. However, it could add more context about the nature of the record (e.g., publication, dataset) to further differentiate from 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?

The schema has 0% coverage (no parameter description), but the description compensates by specifying that the 'id' parameter is a 'Zenodo id', adding meaningful context beyond the schema's type-only definition. The example further aids understanding.

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

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

The description 'Single record by Zenodo id.' clearly specifies the verb ('get' implied), resource ('record'), and scope ('by Zenodo id'). It effectively distinguishes from sibling tools like 'record_files' and 'community_records'.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of when not to use it or any selection 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, idempotentHint, and non-destructive nature. Description adds value by specifying return content (file names, sizes, checksums, URLs), but doesn't disclose potential pagination or rate limits.

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

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

Single, well-structured sentence that front-loads the main action and lists return info. No wasted words.

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

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

For a simple tool listing files, the description covers purpose, required parameter, and return value. Output schema exists so return structure is documented. No gaps.

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

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

Schema has 0% coverage, but description explains that 'id' is a numeric identifier, compensating for the lack of schema documentation. Provides clear semantics beyond the schema type.

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 'List files attached to a Zenodo record by its numeric id' with specific verb and resource, and distinguishes from sibling tools like 'record' and 'community_records' by focusing on file listing.

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?

Implies prerequisite of having a numeric record id but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives, which are clear from context but not directly stated.

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 (idempotentHint true), description adds scoping by identifier, persistence differences for authenticated vs anonymous users, and 24-hour retention for anonymous sessions.

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 sentences, front-loaded with purpose, every sentence provides useful information. No wasted or redundant content.

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

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

Given no output schema, description focuses on input and behavior. It explains scope and persistence but does not specify return value. Sufficient for a simple write operation.

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

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

Schema covers both parameters with descriptions; description adds value by suggesting example keys and values (e.g., 'subject_property', 'target_ticker'), enhancing semantics beyond schema alone.

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

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

The description clearly states the tool saves data for later reuse across conversations or sessions, with specific examples. It distinguishes from sibling tools recall and forget.

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

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

Provides explicit usage context: 'Use when you discover something worth carrying forward.' Mentions pairing with recall and forget but does not explicitly state when not to use.

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavior: it cascades through several lookup endpoints, labels identifiers with sources, states unresolved identifiers explicitly, degrades gracefully if GLEIF/OpenFIGI are unavailable, and handles non-US issuers via ISIN-to-LEI mapping. No contradiction with annotations.

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

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

The description is long but well-structured: it opens with example queries and a clear purpose, then breaks down supported types with details. Every sentence adds value, though the density and length could be slightly tightened. The front-loaded core statement aids quick comprehension.

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

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

With no output schema, the description must cover return values and edge cases, and it does thoroughly: it explains company/drug outputs, unresolved identifiers, ISIN resolution behavior, graceful degradation, and internal cascading. This is highly complete for a complex tool with two entity types and multiple data sources.

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 substantially expands on the input schema by specifying accepted input forms (ticker, CIK, ISIN, name for company; brand/generic for drug) and detailed output identifiers per type (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand). The schema only provides a simple enum and examples, so the description adds significant meaning.

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

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

The description clearly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' — a specific verb+resource. It also lists supported types (company, drug) and explicitly distinguishes it from siblings with '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 when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains it replaces 2-3 manual lookups. However, it does not mention alternatives or when not to use it, so it lacks full exclusion clarity.

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, openWorld, idempotent, non-destructive. Description adds behavioral details: 'probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized'. No contradictions; provides useful process context.

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

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

Three sentences: first states core action, second explains process, third gives use case. No redundant words; front-loaded with primary purpose.

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

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

For a tool with 4 parameters (1 required) and no output schema, the description covers input semantics and return format (ranked list with score, confidence, signal density). Complete enough for AI to use 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%, but description adds value by explaining that 'entities' first entry is the subject, 'context' disambiguates names, and 'models'/'_apiKey' relationship. This goes beyond basic schema descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with specific verb 'Compare' and resource 'AI presence'. It distinguishes from sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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

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

Provides clear context for use: 'useful for competitive AI-marketing audits' and a concrete example. However, lacks explicit when-not-to-use or alternative tools like 'compare_entities' that might also handle multi-entity 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?

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and a `sources_failed` list indicates timeouts. 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 relatively long but every sentence serves a purpose: composite nature, use cases, return fields, limitations, and fallback behavior. It is well-structured with clear sections, though slightly verbose in the return details.

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

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

With no output schema, the description thoroughly explains the return structure (summary block, advisories, links, alternative versions) and covers edge cases like partial failures and ecosystem restrictions. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: scoped packages (e.g., '@types/node') are accepted, and version defaults to latest when omitted. This adds moderate value beyond the schema.

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

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

The description explicitly states the tool's composite purpose: checking npm packages for license, advisories, version history, and bundle size in one call. It clearly distinguishes from sibling tools by focusing on npm dependency analysis.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes ecosystem limitations ('NPM ecosystem only in v1') and directs users to deps.dev:version for other package ecosystems.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds context about the specific repository (Zenodo) and what is returned (metadata, DOI, file links), going beyond the annotations. However, it does not mention pagination behavior or rate limits.

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

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

The description is two sentences long, front-loaded with the core purpose, and every phrase adds value. No redundant or vague wording.

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 6 parameters, 1 required, and an output schema, the description covers the key aspects: search domain, query, filters, and return types. It omits explicit mention of pagination (page/size) but the schema examples imply paginated results, so the gap is minor.

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

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

Schema description coverage is 50%, with descriptions for 'sort', 'type', and 'communities' but none for 'page', 'size', or 'query'. The description clarifies that 'query' is a keyword search and enumerates filter options, partially compensating for missing schema details, but 'page' and 'size' remain unexplained.

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 tool searches the Zenodo repository for various research outputs by keyword. It explicitly lists filter options (type, community, sort order) and return contents (metadata, DOI, file links), distinguishing it from sibling tools by naming the specific repository and result types.

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

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

The description explains what the tool does but does not provide guidance on when to use it versus alternatives like 'deep_research' or 'search_within'. No explicit exclusion criteria or recommended contexts are given, leaving the agent to infer usage from the description alone.

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 details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and return of offsets/scores. 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?

Concise, well-structured paragraph: purpose, usage, technical details. Every sentence adds value; no redundancy.

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

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

Though no output schema, the description explains return format (passages with offsets and scores), limits, embedding model, cap, and pairing with other tools. Complete for the tool's complexity.

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

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

All three parameters are described in the schema (100% coverage). The description adds context: text is document text with max chars, query is natural-language with examples, limit has range 1-20 and default 5.

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

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

The description clearly states the tool performs 'semantic search inside a fetched record', specifying the verb and resource. It distinguishes itself from siblings like 'search' (external) and 'record' (fetching) by focusing on internal semantic 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 when the record is too big to cram into the prompt' and recommends pairing with 'ask_pipeworx_grounded', providing clear context and alternatives.

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

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

Annotations indicate non-readonly, open world, idempotent, non-destructive. Description adds behavioral context such as SMS rate limits, phone verification, webhook signing secret returned once, and auto-disabling on failures. 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?

Well-structured and sufficiently detailed without being overly verbose. Front-loads the purpose and return value. Some redundancy between description and input schema could be trimmed, but still concise.

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

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

Given no output schema, description adequately explains the return value (subscription id). Covers authentication, all subscription types, parameters, delivery channels, and important constraints (rate limits, verification). No gaps for a subscription creation tool.

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

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

Schema coverage is 100% (baseline 3). Description greatly enhances parameter understanding with concrete examples, constraints (e.g., phone must be verified), and behavior (webhook secret returned once), adding significant value beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription id. It lists specific event types and delivery channels, distinguishing it from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

Provides clear context: requires Pipeworx OAuth account, explains type-specific parameters, and delivery details like SMS caps. However, does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the output structure (category-bucketed examples with tool+argument shapes) and the effect of the topic parameter. It does not contradict annotations.

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

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

The description is front-loaded with alternative phrasings and usage hints. It is informative but slightly verbose. Every sentence adds value, though it could be trimmed slightly.

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

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

For an onboarding tool, the description fully explains its purpose, behavior, and usage. It covers all necessary information for an agent to decide when and how to invoke it, even without an 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%. The description adds meaning by listing specific topic values (finance, pharma, etc.) and explaining the difference between omitting (full spread) and passing topic (focused). This goes beyond the schema's generic description.

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

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

The description clearly states the verb+resource: 'Returns category-bucketed example questions' and distinguishes from sibling tools by positioning it as the onboarding entry point. It lists specific categories and mentions that it uses the live catalog.

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' and explains when to call with no arguments vs passing a topic. It also mentions meta-tools as alternatives, providing clear guidance on when to use this tool.

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

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

Adds behavioral context beyond annotations: explains that the row is deactivated (not deleted) and historical events remain via recent_alerts. 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?

Two concise sentences, front-loaded with purpose. Every sentence adds value with 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 simple tool with full schema coverage and annotations, description adequately covers behavior (deactivation, ownership). No output schema, but behavior is sufficiently explained.

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 id as 'Subscription id (uuid) returned by subscribe.' Description reinforces but does not add significant new meaning 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?

Clearly states the action ('Cancel a subscription') and resource ('by id'), with specific verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when the tool is applicable. Does not explicitly mention alternatives, but context is clear.

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

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

The description adds substantial behavioral context beyond the annotations: it clarifies the critical distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source found), explains the return payload (verdict, value, citation, reasoning), and discloses two distinct processing pipelines. This is far beyond what annotations provide, with 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 long but well-structured: it leads with natural-language trigger phrases, then purposes, process, return values, and important caller warnings. The length is justified by the tool's complexity, but some sentences (e.g., 'Replaces 4–6 sequential calls') are somewhat promotional and could be trimmed without losing critical 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?

This is a complex tool with no output schema, so the description must cover return values and semantics. It does: all six verdicts are listed, could_not_verify vs unsupported is explained, the grounded vs structured path is described, and the actual value with citation is mentioned. This is sufficient for an agent to correctly interpret results.

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

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

Schema description coverage is 100%: both claim and tolerance_pct have detailed schema descriptions, including examples and edge-case guidance. The main description does not add significant parameter-specific information beyond what the schema already covers. Per the baseline, a score of 3 is appropriate when the schema carries the load.

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 tool, using strong verbs like 'fact check', 'verify', 'confirm or refute'. It distinguishes itself by specifying the dual-path approach (SEC EDGAR for financial claims, grounded pipeline for others), which differentiates it from generic search/ask 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 explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal routing paths and implies efficiency by saying it replaces 4-6 sequential calls. However, it does not name alternative sibling tools to consider, so the exclusion guidance is implicit rather than explicit.

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