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 declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds meaningful behavior beyond that: it routes to sub-tools, fills arguments, and returns pipeworx:// citation URIs. For a tool with no output schema, that return-format disclosure is valuable, though more caveats or edge-case behavior would push it higher.

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

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

The description is long but information-dense: domain list, routing behavior, usage triggers, examples, and alternatives all earn their place. The all-caps cues like 'PREFER OVER WEB SEARCH' and 'START HERE' aid scanning, though the paragraph could be tightened 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 a single-required-parameter tool with no output schema, the description is largely complete: it covers scope, examples, alternatives, and citation return behavior. The only notable gap is not explicitly differentiating this main tool from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value above the schema by listing trigger phrases ('what is', 'look up', 'find', 'get the latest') and concrete example questions, which clarify the expected natural-language form of the single required parameter.

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

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

The description clearly states a specific verb-resource behavior: it routes factual questions to 5,798 tools across 1,517 verified sources and returns structured answers with citation URIs. The listed domains and examples make the purpose concrete, and the explicit 'PREFER OVER WEB SEARCH' distinguishes it from an obvious alternative.

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

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

The description explicitly says when to use it: for factual questions about real-world data, even when web search could answer. It also names an alternative, deep_research, for broad/multi-part questions, and notes that breaking-news questions route to live news packs. This gives clear, decision-ready 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 substantial behavioral context beyond the annotations: identical routing surface, candidate routing improvements enabled live only when under test, no active candidate currently, and no fallback—it is a full working router. It also discloses that behavior may change over time as candidates are tested, which is exactly the kind of transparency an agent needs.

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 somewhat long but every sentence carries information relevant to safe invocation: beta status, current behavior, usage instructions, and comparison against the stable router. It front-loads the core identity and then adds the operational caveats efficiently, with only minor redundancy around the current candidate status.

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

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

Given the annotations already cover safety and the schema covers parameters, the description completes the picture with current-state behavior, routing intent, and the fact that the response shape is identical to ask_pipeworx. It does not independently describe the response format, but that is mitigated by referencing the well-known sibling with the same response shape.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The description adds no new per-parameter meaning beyond saying the tool takes the same arguments as ask_pipeworx, so the schema carries the semantic load. This matches 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?

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that accepts a natural-language question and routes across 5,798 tools. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. It still leans on the ask_pipeworx sibling for full context, so it is clear but not fully standalone.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, which gives concrete when-to-use guidance. It also explains that results are compared against the stable router to decide merges, but it does not explicitly state when not to use it or name all alternatives such as ask_pipeworx_grounded.

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?

Read-only, idempotent, and non-destructive traits are already in annotations; the description adds meaningful behavioral detail by stating the answer is extracted ONLY from tool results, listing the exact refusal_reason values, and disclosing the extra LLM call cost. 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 dense but every sentence earns its place: purpose, routing mechanism, grounding behavior, return format, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with purpose and keeps the most actionable guidance near the end without padding.

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 a simple single-parameter schema and no output schema, the description compensates fully by specifying both success and refusal return shapes, listing refusal reasons, naming the sibling for casual use, and stating when high-stakes reads apply. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the schema already documents the question parameter and its aliases, so the description carries no parameter burden. The description adds no new parameter-level meaning, which is acceptable under the baseline for fully covered 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 opens with a specific, actionable purpose ('Hallucination-resistant answer mode for high-stakes reads') and immediately differentiates itself from sibling ask_pipeworx by describing the extraction-only grounding behavior. It also specifies the success and refusal result shapes, leaving no doubt about what the tool does.

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

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

Provides explicit guidance on when to use ('whenever an answer will be quoted, cited, or acted on') and when to prefer the sibling ('prefer ask_pipeworx for casual lookups'), including the concrete tradeoff ('costs one extra LLM call'). This is model routing guidance, not just a vague context.

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

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

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?

The annotations already mark the tool read-only, open-world, idempotent, and non-destructive. The description goes far beyond that by disclosing internals: question decomposition, parallel routing, the findings packet structure, gap reporting, contradiction detection, no invented evidence at the gaps, the conditional citation_uri behavior, semantic excerpting, and expected latency. This is unusually rich behavioral disclosure with no contradiction.

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

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

The description is dense and front-loaded with the most decision-critical facts: account requirement, free tier, and the sibling to use when unsigned. It is long but packed with useful behavioral detail; some awkward parenthetical asides and overlapping depth explanations make it slightly heavier than ideal, but no sentence is filler.

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

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

For a complex research tool with no output schema, the description explains what the agent should expect back: evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], and fetchable citation URIs. Combined with the high-coverage schema and annotations, nothing critical is missing 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 coverage is 100%, so baseline is 3. The description does not add meaningfully to the parameters beyond what the schema already explains; depth behavior and the question's broad/multi-part nature are both already captured in the schema descriptions. It provides context for timing but not independent parameter semantics.

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

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

The description names a specific action — grounded multi-source research over Pipeworx's 1,517 structured data sources in a single call — and clearly marks it as distinct from open-web search. It also differentiates from siblings like ask_pipeworx by specifying its best use for broad/multi-part questions.

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 when-not-to-use guidance: if not signed in use ask_pipeworx, and for a single lookup use ask_pipeworx instead. It also notes tier restrictions for depth options, leaving little room for mis-selection.

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

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

Annotations already declare readOnlyHint=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 well beyond the readOnly/openWorld/idempotent annotations: it details cross-source fan-out, per-section output semantics, soft-fail behavior for USPTO, expected empty fda_products for small-molecule companies, and the resolved:false path for private companies. Empty sections are explicitly framed as real 'no data,' not bugs.

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

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

The description is long but every segment earns its place: trigger examples, usage preference, source list, output shape, failure modes, and resolution behavior. It is front-loaded with the most important call-pattern signal and structured so an agent can parse it 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?

With no output schema, the description carries the burden of explaining return structure, and it does so thoroughly: listed fields, source fallbacks, expected-empty cases, and input resolution behavior. For a complex aggregation tool with 2 parameters, nothing essential is missing.

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

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

Schema coverage is 100% and the schema already documents type/value forms, including ticker, CIK, and company-name examples. The description reinforces these but adds little genuinely new parameter meaning; the private-company behavior is more about output than parameter semantics.

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

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

The description opens with concrete user utterances and states the tool's exact function: 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from single-pack SEC/XBRL/news lookups by emphasizing the holistic, fanned-out nature of the call.

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

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

It explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack lookups when the user wants a holistic view, and gives trigger-phrase examples. It does not spell out when NOT to use it (e.g., a quick single fact), so it falls just short of full when/when-not coverage.

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?

The description is exceptionally transparent about behavioral caveats: pairing_unverified is always set, temporal_alignment_unknown is not the same as confirmed alignment, unknown metric_type/match_subtype legs are never paired, fees are gross not net, and compatibility_codes[] can be non-empty even when matched_pairs>0. These details go far beyond the annotations and are critical for correct interpretation of results.

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 nearly every sentence earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with the core purpose and then organized into labeled sections for modes, response, safety fields, and caveats. It could be tightened, but the density is justified by the need to prevent misinterpretation of spread data.

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 complex cross-venue comparison tool with no output schema, the description covers return values, compatibility codes, per-entry flags, skipped-leg counters, temporal alignment semantics, fee disclosures, and the reliability of pair matching. An agent has enough information to call the tool correctly and interpret its response safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context about how topic, kalshi_event_ticker, and polymarket_event_slug interact, and notes that both modes run the identical token-overlap matcher, but it does not add substantial new parameter-level meaning beyond what the schema already provides.

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

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

The description opens with a specific purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes beyond the title by explaining that the delta is only meaningful when bet shapes are equivalent and by naming the two operational modes. Although it does not explicitly name sibling tools, the emphasis on 'spread' rather than executable edge differentiates it from tools like polymarket_arbitrage.

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

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

The description gives clear mode-selection guidance: use the topic shortcuts for pre-mapped macro events or supply explicit kalshi_event_ticker and polymarket_event_slug for custom pairings. It also warns that pre-mapped topics often return compatibility_warning and are not automatically tradeable. It does not explicitly contrast with sibling tools such as polymarket_edges or polymarket_arbitrage, so the when-not-to-use guidance is implicit rather than direct.

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/openWorld/idempotent annotations, the description reveals non-obvious behavior: it cascades through several lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns unresolved identifiers explicitly instead of omitting them, and returns figi_candidates when a name matches multiple instruments. No contradiction with annotations exists.

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

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

The description is long and dense, but nearly every sentence adds operational value—edge cases, fallback behavior, supported instruments, and output labeling. It is front-loaded with examples and use cases. The main weakness is verbosity and nested parentheticals, which could be tightened without losing meaning.

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

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

Given there is no output schema, the description carries the full burden of explaining what the tool returns: source-labelled identifiers, an unresolved list, figi_candidates for ambiguous matches, and a RxNorm citation URI. It also covers input constraints, unsupported/edge cases, and degradation behavior, making it sufficiently complete 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains accepted input formats for each type, clarifies that ISIN resolves to the issuing legal entity, and warns to pass only the entity name with a concrete bond-issuer example. This materially reduces the chance of malformed calls.

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: resolving user-spoken names to canonical/official identifiers, with concrete query examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes the tool from siblings by positioning it as the first step whenever a name needs to become an ID, covering both 'company' and 'drug' entity types explicitly.

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

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

The description gives clear when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported inputs (ticker, CIK, ISIN, company name, drug brand/generic) and types. It does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of a full 5.

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

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

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