Guidetopharmacology

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial value by detailing the output structure, the default free model, and the requirement for a user-provided API key for Anthropic, including cost responsibility. 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 two sentences plus a use-case line, with no wasted words. It front-loads the core action and output, then provides optional details and context. Extremely concise yet comprehensive.

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 the return format (per-model score, confidence, signals, raw_response, plus combined view). It covers the 4 parameters well. However, it could clarify what 'signals' entails, but overall it is sufficient for an agent to understand the tool's inputs and outputs.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the default model for the 'models' parameter, the purpose of '_apiKey', and how 'context' aids disambiguation. This enriches the agent's 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 function: probing LLMs for knowledge about an entity and returning a visibility score. It specifies the default model and optional Anthropic probing, aligning with the name. However, it does not explicitly differentiate from similar sibling tools like 'scan_competitor_ai_presence', which might cause confusion.

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

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

The description offers use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', providing context for when to use. However, it does not state when not to use or compare with alternative tools, leaving ambiguity about 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond these: it routes across thousands of sources, fills arguments automatically, returns structured answers with citation URIs, and works on every tier with one fast call. 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 long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') followed by scope, examples, and alternatives. Each section earns its place, though it could be tightened. It is well-structured and not redundant.

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 (routing to thousands of sources) and lack of an output schema, the description explains the return format (structured answer with citation URIs), scope of sources, and when to use alternatives. It covers usage examples and limitations implicitly by naming when to step up. Could detail output structure more, but adequate for 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 coverage is 100% with detailed descriptions for each parameter alias. The description does not add any parameter-level semantics beyond what the schema provides; it just restates that the parameter is a natural-language question. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states what the tool does: 'Routes the question to the right one of 5,558 tools across 1461 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses specific verbs (routes, fills, returns) and a resource, and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It also names alternatives and specific conditions for stepping up: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This exceeds basic context by offering clear exclusions and alternatives.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description discloses the experimental nature, the possibility of live routing changes during candidate tests, and the fact that results are compared against the stable router. It also clarifies it is a full working router, not a fallback.

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 front-loaded, information-dense sentences. Each sentence adds necessary context: identity, current state, usage, and behavioral clarification. 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 single-required-param tool with annotations and no output schema, the description covers identity, experimental status, current behavior, usage guidance, and relationship to the stable sibling. Fully adequate.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description merely says 'same arguments' without adding new meaning, so it does not raise the baseline, but also doesn't detract.

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 variant of ask_pipeworx, an identical universal router with the same 5,558 tools, arguments, and response shape. It explicitly positions it as the experimental edge alongside the stable ask_pipeworx, distinguishing it from siblings.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes it currently matches ask_pipeworx exactly with no active candidate. This provides clear when-to-use context and implicitly contrasts with the stable alternative.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses critical behaviors: it makes an extra LLM call, returns a structured object with evidence and refusal_reason, and explicitly refuses when data doesn't directly answer. The refusal reason enums (not_in_source, no_tool_match, etc.) add deep transparency. 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?

Although longer than many tool descriptions, every sentence earns its place: purpose, routing behavior, return format, use cases, and cost trade-off. The information is front-loaded with the core value proposition, and the refusal schema is compactly listed. The structure efficiently packs high-value detail 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?

With no output schema, the description fully specifies the return shape on success and refusal, including refusal reason enums. It also covers the extra cost, alternatives, and high-stakes usage contexts. For a tool of this complexity, the description provides all necessary context for an agent to decide and invoke it correctly.

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

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

The input schema has 100% coverage, describing all six parameters as aliases for 'question.' The description adds no further parameter detail, which is acceptable because the schema fully documents the alias structure. However, it does not clarify which alias is preferred or any formatting expectations, so the baseline of 3 is appropriate.

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

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

The description opens with a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the tool extracts answers using only tool result content, and explicitly differentiates from the sibling tool 'ask_pipeworx' by describing the same routing but with grounded extraction. This makes the tool's unique value unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' directly naming the alternative. This is exemplary usage 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 goes far beyond the annotations by detailing the resolution process, classifier fan-out, response shapes with specific fields, resolver contract, parent event extraction, news fallback behavior, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread indicators), and resolution-rule risk parsing. This is excellent behavioral transparency.

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 sections. It is front-loaded with a clear opening sentence. However, some redundancy exists (e.g., repeated mentions of fan-out examples), and it could be tightened while retaining key information. Still, for the tool's complexity, it is reasonably organized.

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

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

Despite having no output schema, the description exhaustively covers response shapes, evidence structure, market matching confidence, parent events, news fields, safety behaviors, and resolution rules. It anticipates agent needs for edge detection and market verification, making it fully complete given the tool's complexity.

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

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

The input schema covers all 3 parameters with descriptions, but the tool description adds valuable context: the 'market' parameter accepts slug, URL, or text; 'depth' has examples and default; 'include_raw' explains when to use true vs false. This adds meaning beyond the schema, though the schema coverage is already complete.

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 'Research' and the resource 'Polymarket bet', and specifies the action of pulling Pipeworx data in one call. However, it does not explicitly differentiate from sibling tools like ask_pipeworx or polymarket_arbitrage, which could cause confusion for an AI agent selecting among them.

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

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

The description provides clear usage examples ('should I bet on X', 'what does the data say about Y') and fan-out examples for different bet categories. However, it lacks explicit guidance on when NOT to use this tool or alternatives, leaving the agent without exclusion 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 openWorldHint, but the description adds valuable behavioral context: it pulls from SEC EDGAR/XBRL for companies (including handling off-calendar fiscal years) and FAERS for drugs. It also reveals that results are sorted by primary metric and that responses include citation URIs. 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 adds necessary information. It front-loads with example triggers, then explains the mechanism, data sources, and output format. Could be slightly trimmed, but the density of useful information justifies the length.

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

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

Given the tool's complexity (two entity types, multiple data sources, variable entity count) and the good annotations/input schema, the description covers all key aspects: data sources, return format, sorting, and use case context. It lacks details on error handling or latency, but overall is sufficient 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?

The input schema provides 100% coverage with clear descriptions for both parameters (type and values). The description enhances this by detailing what data is retrieved for each entity type, specifying value formats (tickers/CIKs for company, names for drug), and clarifying the count constraints (2–5). This adds significant context beyond the schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs. It provides explicit trigger phrases like 'compare X and Y', 'which is bigger', and 'rank these companies', making the purpose unmistakable. It also distinguishes itself from sibling tools by noting it replaces sequential single-entity 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 gives explicit when-to-use guidance with multiple example user intents. It further states 'ALWAYS PREFER over sequential single-pack lookups', directly telling the agent when this tool is superior to alternatives like entity_profile. It also clarifies the tool's efficiency gain by replacing 8–15 sequential lookups.

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

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

Annotations already declare readOnly/idempotent/destructive false, but the description goes far beyond: it discloses account/paid plan requirements, latency expectations, gaps[] handling, contradictions[], citation_uri resolvability, semantic excerpting, and the hop field. No contradictions with annotations; substantial additive behavioral context is provided.

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 densely informative; nearly every sentence adds value. It could be tightened slightly (e.g., gaps[] is mentioned multiple times), but the front-loaded account requirement and clear structure make it effective for a complex tool.

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

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

For a tool with no output schema and two parameters, the description is remarkably complete: it covers return packet contents, gaps/contradictions, citation behavior, timing, exclusions, and pricing. It leaves little ambiguity about what the tool returns and when it fails, which is excellent given 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?

Though the input schema already covers both parameters (100%), the description enriches them significantly: it explains what each depth ('quick'/'standard'/'thorough') does in terms of facet count, hop behavior, and contradiction scanning, and clarifies that the question parameter accepts broad, multi-part queries. This goes well beyond the schema's enum descriptions.

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

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

The description clearly states the tool's core function: grounded multi-source research over structured data sources in one call. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, providing a specific verb (research), resource (structured data sources), and scope (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 explicitly identifies alternatives (ask_pipeworx for single lookups, current news). It also notes account requirements and a fallback tool if not signed in, making usage conditions unambiguous.

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

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

Annotations already mark the tool as readOnlyHint=true and idempotentHint=true, so safety is clear. The description adds value by explaining the output includes 'full input schemas (with curated examples)' and that results are 'ready to call directly', which goes beyond annotations. No contradictions.

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

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

The description is four sentences: purpose, usage examples, output details, and workflow guidance. It is front-loaded and informative without being verbose. Minor redundancy in listing aliases could be trimmed.

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 explains what is returned (names, descriptions, schemas). It covers the main inputs and their purpose, and provides usage context. It is sufficiently 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 coverage is 100%, so parameters are already documented. The description provides example queries and notes that the tool accepts multiple aliases, but does not add deep semantics beyond the schema. It is adequate but not exceptional.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and emphasizes that it returns tools ready to call, which distinguishes it from sibling tools that likely perform specific actions.

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 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on when to use it and suggests a primary workflow.

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 substantial behavioral context beyond annotations: it fans out across multiple sources, returns specific fields (cik, filings, fundamentals, patents, news, LEI), notes that patents API may sunset and soft-fails, and describes news fallback. 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 front-loaded with example queries and uses bolding for key guidance. Every sentence adds value, but it is somewhat dense with multiple details. Could be slightly streamlined, but it remains clear 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 no output schema, the description thoroughly explains all return fields and sources. It covers input constraints (ticker/CIK only), behavioral aspects (parallel call, fallbacks), and limitations (patents API sunset). The tool's complexity justifies the level of detail.

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 high. The description adds meaning beyond schema: clarifies that type only supports 'company' and value can be ticker or zero-padded CIK, and explicitly states names are not supported. This provides critical usage context that the schema alone does not.

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 and resources like 'full cross-source profile of a US public company' and provides numerous example queries ('Tell me about X', 'research Acme', etc.). It clearly distinguishes from chaining single-pack lookups by explicitly stating 'ALWAYS PREFER over chaining...'.

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

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

Explicitly states when to use ('ALWAYS PREFER...when the user asks for a holistic view') and when not to use ('names not supported - use resolve_entity first if you only have a name'). Also mentions fallback behavior and API sunset, guiding appropriate invocation.

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 readOnlyHint=false. The description reinforces this by stating 'Delete' and adds behavioral context by explaining when deletion is appropriate (stale context, end of task, clearing sensitive data). There is no contradiction with annotations.

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

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

The description is exceptionally concise: two sentences with no redundancy. The first sentence clearly defines the action and the second provides usage guidance. Every word contributes value.

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

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

For a simple delete-by-key tool with one required parameter and no output schema, the description covers the purpose, usage scenarios, and pairing with related tools. It is fully complete given the tool's low 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 single parameter 'key' is fully described in the schema with 'Memory key to delete'. The description does not add additional information beyond the schema, such as key format or constraints. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It uses a specific verb ('Delete') and resource ('memory by key'), and distinguishes itself from sibling tools 'remember' and 'recall' by indicating it is the deletion counterpart.

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

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

The description explicitly provides usage scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall', though it does not explicitly state when not to use it or offer direct 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?

Description details the process (fetches page, extracts title/description/links, outputs llms.txt markdown) and output format, adding value beyond annotations (readOnlyHint, idempotentHint). 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?

Three sentences, front-loaded with purpose, process, and use cases. No extraneous words; every sentence adds value.

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

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

Given simple tool with two well-documented parameters, annotations covering safety and idempotency, and output described as a text blob, the description is fully adequate.

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

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

Schema coverage is 100%, so baseline is 3. Description repeats schema info for max_links (default 25, max 50) and url (example) without adding new 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?

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying verb, resource, and purpose. No sibling tool duplicates this function, so differentiation is inherent.

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

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

Explicit use cases are provided (client indexing, own project, competitor audit), but no exclusions or alternatives are mentioned. Clear context for when 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context: ligand name resolution, the response naming the actual ligand read, and the 'keyless' requirement. These are meaningful behavioral disclosures beyond the annotations.

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

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

The description is concise, well-structured, and front-loads the key purpose. Every sentence earns its place: purpose, data source, return fields, input options, resolution behavior, and keyless note. 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?

With no output schema, the description compensates by detailing exactly what is returned. It also explains input resolution and the keyless aspect. Minor gaps like default limit behavior are already covered by the schema, so this is effectively complete for the tool's complexity.

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

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

The schema already describes all three parameters with 100% coverage. The description adds extra meaning by clarifying that 'ligand' can be a name that is resolved while 'ligand_id' is the GtoPdb identifier, and that either can be used. This enhances the schema without redundancy.

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

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

The description begins with 'What proteins a drug acts on', a specific and informative statement of the tool's purpose. It details the curated target interactions and lists the returned fields (protein name, interaction type, action, affinity), fully distinguishing it from sibling search tools.

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

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

Clear context is provided: this tool is for querying target interactions for a ligand, with examples of how to pass a drug name or GtoPdb ID. It does not explicitly mention alternative tools or exclusion criteria, but the purpose is specific enough to guide appropriate 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds return fields and default filtering to active subscriptions, but does not disclose additional behavioral traits 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 clear sentences, zero wasted words: first sentence defines purpose and output, second sentence gives usage guidance.

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 annotations and a well-documented schema, the description covers purpose, return fields, usage, and parameter implication, making it fully sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema for the single parameter; it only implies default behavior.

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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from siblings 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?

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use it.

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

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

Annotations provide only boolean hints (all false), so the description carries the burden of behavioral context. It richly discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow, daily digest reading, and the fact that it is free and doesn't count against tool-call quota. 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?

Although the description is long, every sentence earns its place: purpose, use cases, exclusion, token flow, and rate limit are all covered without redundancy. It is front-loaded with the main purpose and then logically sequences caveats. The structure is appropriate for a tool with submission and follow-up mechanics.

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

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

For a feedback tool with a nested context object and four parameters, the description covers all essential aspects: what it does, when to use it, when not to, how the claim_token follow-up works, rate limits, and cost. No output schema exists, but the description explicitly mentions the returned claim_token. This is a complete and self-contained explanation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This enriches parameter understanding beyond the raw field descriptions.

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

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

The description opens with a specific verb phrase: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool's purpose as submitting feedback about Pipeworx tools and distinguishes itself from sibling research/query tools. It also differentiates from other MCP servers by explicitly stating it is only for this Pipeworx connection.

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 by mapping feedback types (bug, feature/data_gap, praise) to concrete examples. It also provides an exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is a clear alternative path, and the claim_token flow further explains how to follow up on a submission.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (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?

The description is extremely concise: one sentence for output, three use cases in a list-like structure, and one sentence for technical details. Every sentence adds value with no redundancy.

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

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

Given the low complexity (one optional parameter, no output schema), the description fully explains what the tool returns (top tools, top packs, call volume) and provides sufficient context. 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?

The single parameter 'window' is fully described in the schema (enum with descriptions). The description adds value by explaining that shorter windows surface hot trends while longer windows show steady-state demand, going 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 returns top tools, top packs, and total call volume over a window. It uses specific verbs ('returns') and resource nouns, and effectively distinguishes itself from sibling tools like 'discover_tools' by focusing on trending data.

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 three explicit use cases (discovering hot sources, confirming canonical choices, aligning use cases). It does not explicitly state when not to use or mention alternatives, but the use cases provide clear guidance.

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

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

Adds significant detail beyond annotations: explains read-only scanning, idempotent behavior, and all trade logic including partition filter, semantic anchor, and fill check. No contradiction with annotations (readOnlyHint, etc.).

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?

While long, every sentence adds value and is well-structured. Front-loaded with purpose and mode selection, then details. Could be slightly more organized, but the complexity warrants the length.

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

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

Comprehensive coverage: explains both modes, response format, fill check, semantic anchor, partition filter, and error conditions. Without output schema, description fully documents return structure and trade signals. 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?

High schema coverage (100%) but description adds value by explaining the purpose and behavior of each parameter: event for specific slug, topic for cross-event scanning, with examples. It clarifies when to use each and the underlying arbitrage logic.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity and partition-sum checks, with distinct modes (event, topic, default scan). It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach and use cases.

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

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

Explicit guidance on when to use each mode: default for trending scan, event for specific market, topic for cross-event scan. Provides example slugs, explains fill check to avoid false trades, and directs to polymarket_fill_risk for custom sizing.

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=true and destructiveHint=false. The description adds extensive behavioral context: caching behavior, response structure, model details, and diagnostic information. 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 long but well-structured, front-loading purpose and then detailing model families and parameters. Every sentence adds value given the complexity, though bullet points or sections could improve readability.

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

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

No output schema, so description fully explains return values: by_segment, fed_candidates/note, _diagnostics, and key fields like edge_pp_net, kelly_fraction. Caching and edge case (Fed bets) are covered, making it complete for the tool's complexity.

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

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

With 100% schema coverage, baseline is 3. The description adds significant meaning beyond the schema, explaining parameter interactions, defaults, and practical usage (e.g., slippage assumptions, min_kelly vs min_partition_leg_kelly differentiation).

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 Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb and resource. It distinguishes from siblings by detailing unique model families and response segments.

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 is built for 'what should I bet on today' and explains when to use it, but does not explicitly contrast with sibling tools like polymarket_arbitrage. However, it provides detailed guidance on parameters and tradeable-edge knobs.

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, indicating safe, non-destructive behavior. The description adds detailed behavioral context: response structure (tracked, expired, snapshot_dates), data freshness caveats, and limitations (TTL, decay computation). 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 front-loaded with purpose and then provides structured details about response and limitations. It is somewhat long but each sentence adds value. Could be slightly shorter but not excessively verbose.

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

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

Despite having no output schema, the description thoroughly explains the response structure and covers all important aspects: tracked edges, expired edges, snapshot dates, and 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% with descriptions for both parameters. The description adds value by specifying defaults, clamping ranges, and listing valid window values ('24hr | 1wk | 1mo') not present in the schema enums.

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 about edge lifespan and contrasts with a fresh edge vs an old one, distinguishing it from siblings like 'polymarket_edges'.

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

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

The description explains when to use the tool (to understand edge duration and decay) and provides context about the difference between new and old edges. However, it does not explicitly name alternative tools for when not to use it, though sibling tools exist.

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

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

Description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint, etc.): it walks the ladder, returns verdicts (clean/degraded/cannot_fill), and for basket mode details per-leg fills, thin_legs, and forced_directional_risk. Annotations already indicate non-destructive, read-only behavior; description confirms and enriches without contradiction.

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

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

The description is long but well-organized: it starts with the core purpose, then clearly separates single-market and basket modes with headings, lists return fields, and ends with usage guidance. Every sentence adds value; nothing is redundant. While dense, it earns its length given the tool's complexity.

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

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

Given the tool's two modes, four parameters, no output schema, and complex behavior (ladder walking, per-leg details), the description is remarkably complete. It covers all inputs, explains all significant return fields, and warns about critical failure modes (partial fills, directional risk). No important aspect is left unexplained.

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 four parameters have descriptions in the schema (100% coverage), but the description adds essential context: explains that market and event are mutually required, describes side auto-detection for basket mode, and clarifies how size_usd is interpreted differently between modes (max spend vs target proceeds vs settlement notional). This goes beyond the schema.

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

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

Description clearly defines the tool as a realizable-vs-theoretical edge check against live CLOB order book depth. It distinguishes between single-market and basket modes, lists specific return fields, and explicitly ties its use to downstream tools like polymarket_arbitrage and polymarket_edges, making its purpose distinct from siblings.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains risks of not using it (partial fills lead to unhedged positions). While it does not list explicit alternatives or when-not-to-use, the context strongly implies appropriate use cases.

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 extensively discloses behavior beyond annotations: it details compatibility warnings, temporal alignment, skipped cross types, and response structure. It is fully consistent with readOnlyHint and other annotations.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the main purpose. It is longer than average but each sentence adds necessary detail for a complex tool.

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

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

Given no output schema, the description fully explains the response (leg-by-leg prices, top_spreads_pp) and safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases and limitations comprehensively.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the ten pre-mapped topics, providing example values, and explaining parameter interaction (override behavior).

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 computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question,' and details two modes (pre-mapped topics and explicit tickers). It is a specific verb+resource that distinguishes it from sibling 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 explains when to use each mode (topic vs. explicit) and warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. It does not explicitly compare to alternative tools but provides clear usage context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: scoping by identifier, behavior when key is omitted (list all keys), and pairing with other tools. No contradictions.

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

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

The description is three sentences, each serving a distinct purpose: action, context, and relationship to siblings. No redundant words, front-loaded with the primary functionality.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description covers all necessary aspects: what it does, when to use it, scoping, and integration with sibling tools. 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the effect of omitting the key (list all) and the purpose of the key parameter. This goes beyond the schema's basic 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 defines the tool's purpose: retrieving a previously saved value or listing all keys. It uses specific verbs ('Retrieve', 'list') and specifies the resource ('value previously saved via remember'). Sibling tools 'remember' and 'forget' are distinct.

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

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

The description explains when to use the tool ('look up context stored earlier') and mentions related tools ('Pair with remember to save, forget to delete'). It does not explicitly state when not to use it, but the context is clear.

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

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

Annotations already declare safe, idempotent read operations. The description adds valuable behavioral details: the contents of each alert, the effect of mark_read on subsequent calls, and that polling works. 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?

Five sentences covering all key aspects without excessive wordiness. Could be slightly tighter by combining the return clause with the field list, 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?

Though there is no output schema, the description compensates by listing returned fields. It explains filtering, side effects of mark_read, and alternative access. Missing explicit pagination details, but default ordering ('most recent') is implied. Fairly complete for a read-only polling tool.

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

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

Schema coverage is 100% with thorough property descriptions. The description adds marginal value by grouping filtering parameters and explaining mark_read's effect, but mostly restates schema info. 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 'Pull fired events from your subscription feed' and specifies the return contents (source, citation_uri, raw event payload). This verb-resource pair is distinct from sibling tools like 'list_subscriptions' or 'recent_changes'.

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 usage guidance: filtering by type and since, using mark_read to manage read state, and mentions polling is acceptable. Also points to an alternative access method (GET endpoint). However, it lacks explicit comparison to sibling tools or when-not-to-use scenarios.

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

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

Adds significant context beyond annotations: describes fallback behavior (GDELT→GNews), notes soft-fail for USPTO due to API sunset, explains return structure (changes grouped by source, total_changes, citation URIs), and idempotency hints are 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 moderately long but well-structured, starting with example queries and covering all aspects. Minor redundancy could be trimmed, but every sentence adds value.

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

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

With full parameter coverage, no output schema, and sufficient annotations, the description covers purpose, behavior, usage, and alternative tools completely, leaving no gaps for an AI agent.

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

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

Schema coverage is 100%, but description adds value by explaining relative shorthand for 'since' (e.g., '30d') and providing examples for 'value' (ticker or CIK), going beyond the schema descriptions.

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

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

The description clearly states it returns a change feed for a company (SEC filings, GDELT/GNews, patents) in a time window. It distinguishes itself from sibling tool 'entity_profile' by explicitly stating when to use the latter for static profiles.

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

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

Provides explicit usage examples ('What's new with X'), states supported entity type (company only), and directs to 'entity_profile' for static profiles, giving clear when-to-use and when-not-to-use guidance.

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

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

Discloses persistence behavior (authenticated vs. anonymous sessions) and scoping. No contradiction with annotations; adds context beyond readOnlyHint and idempotentHint flags.

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 five-sentence paragraph with main purpose upfront and no redundant information.

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

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

Covers all essential aspects: purpose, usage, parameters, persistence, and relation to companion tools. No output schema needed for this simple write tool.

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

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

Schema coverage is 100%, with clear descriptions for key and value. The tool description adds no additional semantic detail beyond what the schema provides.

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

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

The description specifies exactly what the tool does: saves data for reuse later. It clearly identifies the resource as key-value pairs scoped by identifier and distinguishes itself from sibling tools like 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?

Explicitly states when to use ('when you discover something worth carrying forward') and pairs it with alternative tools (recall, forget) for retrieval and deletion.

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, but the description adds rich behavioral context: it labels every identifier with its source, states unresolved identifiers explicitly under `unresolved`, handles ISIN-to-LEI mapping for non-US issuers, and gracefully degrades if GLEIF/OpenFIGI are unavailable. 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?

While the description is long, it is densely packed with useful information and structured by examples, usage directive, and supported types. Every sentence contributes functional detail (source labeling, degradation, cascading lookups) and there is no repetition of schema content or filler.

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

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

With no output schema, the description fully explains return semantics: resolved and unresolved identifiers, source attribution, and internal cascading. It covers edge cases like non-US issuers and service unavailability, making it a complete reference for invoking the tool correctly.

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

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

The schema defines type and value, but the description adds significant meaning: it details accepted input formats per type (ticker, CIK, ISIN, company name for 'company'; brand or generic name for 'drug'), provides examples like 'CH0038863350' and 'ozempic', and explains how ISIN resolves to legal entity via GLEIF. This goes well beyond the schema's basic descriptors.

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 example queries and then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This clearly identifies the verb (resolve), the resource (name to identifiers), and separates it from siblings like entity_profile or compare_entities by focusing on identifier resolution.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID.' This is a strong directive for when to invoke the tool. It also explains that each call replaces 2-3 manual lookups, giving a clear sense of efficiency and context without needing to name alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, and the description adds behavioral details: it 'probes each entity with ai_visibility_check', 'ranks by score', and returns 'score, confidence, signal density per entity'. This adds value beyond the annotations.

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

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

Three sentences: first states core purpose, second explains mechanism, third gives use case and output. Every sentence is substantive, front-loaded, and free of 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?

With 100% schema coverage, thorough annotations, and no output schema required, the description fully covers the tool's functionality, inputs, process, and outputs. It includes a usage example and specifies what the returned data includes.

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

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

Schema description coverage is 100%, so baseline is 3. The description explains the overall role of parameters (e.g., 'entities' are 2-8 entities, 'context' disambiguates) but does not add new semantic 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 specifies the verb 'compare', the resource 'AI visibility across multiple entities', and the actions 'probes, ranks, surfaces'. It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison).

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 positions the tool for 'competitive AI-marketing audits' with a concrete example. It provides clear context but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds crucial details: partial failures with graceful degradation, potential 5-30s delay for bundlephobia first measurement, and the behavior of sources_failed.

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

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

The description is a single paragraph but well-organized: purpose first, then usage, then output details, then limitations. Could be slightly more structured, but content is efficient and 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?

Even without an output schema, the description comprehensively lists all return fields and explains edge cases like partial failures and timeouts. Covers ecosystem limits (npm v1) and alternative usages.

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%, but the description adds meaning: clarifies that scoped packages are accepted for package parameter, and that version defaults to latest. This provides context beyond the schema.

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

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

The description clearly states the tool's function as a composite check for npm packages, using deps.dev and bundlephobia. It distinguishes itself from siblings by specifying the npm ecosystem and the composite nature.

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

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

Explicitly states when to use: for questions about safety, popularity, size, or cost of adding an npm package. Also notes that non-npm ecosystems fall under a different tool, providing clear alternatives.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive nature. Description adds 'keyless' and specifies output fields, but does not significantly extend beyond annotations.

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

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

Three sentences perfectly front-loaded with essentials: database, verb, output, usage chain, and keyless status. Zero wasted words.

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

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

With strong annotations and a simple 2-param schema, description fully covers purpose, usage, output, and linkage to other tools. 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% and parameter descriptions are clear. Description adds no additional meaning beyond 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?

Uses specific verb 'Search' and resource 'ligands' in Guide to PHARMACOLOGY. Distinguishes from siblings like search_targets and ligand_interactions by explicitly stating the database and complementing other databases.

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

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

Explicitly instructs to use returned ligand id with ligand_interactions, and notes it complements ChEMBL/DrugBank. Almost perfect, but lacks explicit when-not scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds value by stating the tool is keyless (no authentication required) and specifying the returned data types. No contradictions.

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

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

The description is three sentences long, front-loads the purpose, and provides essential usage guidance without unnecessary words. It is efficient though could be slightly more structured (e.g., bullet points).

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 lists returned fields (target id, abbreviation, type) and gives examples of types, which is helpful. It also mentions complementing ChEMBL/DrugBank. It lacks details on pagination or error handling, but annotations and schema cover most needs.

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 both parameters described and examples provided. The description restates the 'name' parameter but adds the important usage hint that the returned target id can be used with target_interactions, which is not in the schema. This earns a baseline score of 3.

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

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

The description clearly states the tool searches the Guide to PHARMACOLOGY for protein targets by name, specifies the returned fields (target id, abbreviation, type), and gives examples of target types (GPCR, etc.). It also contrasts with sibling tools like search_ligands and target_interactions by suggesting using the returned id with target_interactions.

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

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

The description explicitly advises using the returned target id with target_interactions to find ligands, and notes that the tool is keyless and complements ChEMBL/DrugBank. It does not explicitly state when not to use this tool, but the usage guidance is clear and actionable.

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

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

Annotations already declare safe read-only and idempotent behavior. The description adds detailed technical context: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. All traits are disclosed without contradiction.

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

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

Two paragraphs with clear first-sentence summary. Every sentence contributes useful information—usage context, technical details, examples. Slightly verbose on the embedding details, but overall well-organized and 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?

For a tool with 3 parameters, no output schema, and moderate complexity, the description covers input constraints (200K chars, truncation), output structure (passages with offsets and scores), and pairing with sibling tools. No gaps in essential information.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value: for 'text' it notes max length and truncation behavior; for 'query' it gives natural-language examples; for 'limit' it states default (5). This is above baseline but not extensively deep.

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

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

The description uses a specific verb ('search') and resource ('inside a fetched record'), provides concrete examples (SEC 10-K, article), and distinguishes itself from sibling tools like ask_pipeworx_grounded. It clearly conveys the tool's unique value.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt'), why to use ('saves context, returns only passages that matter'), and how to combine with a sibling (ask_pipeworx_grounded). No ambiguity about appropriate usage.

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

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

Annotations indicate readOnlyHint=false (write), idempotentHint=true, destructiveHint=false. The description details delivery channels, limits (SMS cap, webhook auto-disable), and that the subscription is persistent. No contradiction; however, idempotency is not explicitly stated, which might be confusing given the annotation.

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

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

The description is well-structured and front-loaded with the main purpose. While somewhat long, every sentence provides necessary context. Minor redundancy could be trimmed, but overall 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 the complexity (5 types, nested params, multiple delivery channels), the description covers key details: return value (ID), auth requirements, and channel behaviors. No output schema, but the description adequately explains the response.

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

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

Schema coverage is 100%, and the description adds significant value by providing concrete examples for each type's params and detailed explanations for delivery options, including limitations and prerequisites.

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 to a live-data event stream. It distinguishes from sibling tools like list_subscriptions and unsubscribe by explicitly focusing on creation.

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

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

The description specifies when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). It lists supported types with examples but does not explicitly mention alternatives or when not to use, though context from siblings implies.

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

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

The description adds significant behavioral context beyond annotations: it explains the output (category-bucketed example questions with exact tool+argument shapes) and notes it draws from a live catalog. It aligns with all annotations (readOnly, idempotent, non-destructive) without contradiction.

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

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

The description is well-structured: front-loaded with alternative phrasings, then output explanation, then usage instructions. Every sentence adds value without unnecessary fluff.

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

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

Given the tool's role as an entry point with no output schema, the description is fully complete: it explains what it returns, how to use it (with and without topic), and when to use it. No additional information is needed.

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

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

Schema coverage is 100% for the single parameter topic, but the description adds value by explicitly stating the default behavior ('omit for a cross-category spread') which is not in the schema. This clarifies usage beyond the schema's enumerated list.

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

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

The description clearly states it is the onboarding entry point for a just-connected agent, listing alternative phrasings like 'what can I ask Pipeworx?' and explicitly returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by instructing to use it first when unfamiliar with the system.

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

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

Explicitly instructs to use this tool FIRST when you do not know what Pipeworx can do, and provides guidance on calling with no arguments for a full spread or with a topic to focus. While it doesn't explicitly list when not to use it, the context clearly implies alternatives (e.g., ask_pipeworx for actual queries).

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. The description adds value by specifying the return content (interaction type, action, binding affinity) and noting that the tool is 'Keyless' (no API key required). No contradictions with annotations.

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

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

The description is very concise: three sentences, each adding essential information. The purpose is front-loaded, and there is no redundant or wasted text. 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?

Given rich annotations (readOnlyHint, idempotentHint, openWorldHint) and complete parameter schema, the description adequately covers return values and context (e.g., 'Keyless'). It explains what the tool returns without needing an output schema. The description is complete for a query tool.

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

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

Schema coverage is 100% with clear parameter descriptions for target_id (including example) and limit (including default). The description reinforces the meaning of target_id by referencing search_targets, but this adds minimal value beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'quantitative ligand interactions for a protein target' in the IUPHAR/BPS database. It specifies what is returned (ligand interactions with type, action, binding affinity) and how to identify the target, effectively distinguishing it from sibling tools like 'ligand_interactions'.

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 a clear prerequisite: 'Given a GtoPdb target id (from search_targets)', guiding the agent to first use search_targets. However, it does not explicitly state when not to use this tool or list alternatives, which would strengthen the guidance.

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

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

Adds significant value beyond annotations: ownership enforcement, deactivation (not deletion), and link to recent_alerts for historical events. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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, each purposeful: action, constraint, consequence. No wasted words. Front-loaded with the core action.

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

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

For a simple 1-param tool with no output schema, this description covers purpose, usage constraint, and post-effect. Annotations provide safety context. Complete for agent decision-making.

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

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

Schema covers 100% of parameter description ('Subscription id (uuid) returned by subscribe'). The description mentions 'by id' but adds no new semantic detail beyond the schema. 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 action 'Cancel a subscription by id' with specific resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

Explicitly states ownership constraint ('you can only cancel your own subscriptions') and hints at when not to use by explaining deactivation vs deletion. Could be more explicit about when to use this tool vs alternatives, but provides solid guidance.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavioral context: it explains the two routing paths (structured SEC EDGAR vs. grounded pipeline), the exact set of verdicts, and the crucial distinction between could_not_verify (a technical failure, not evidence) and unsupported (no source coverage). This is exactly the kind of behavioral nuance that helps an agent use the tool correctly.

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-organized, front-loading trigger phrases, then defining the core function, routing logic, return format, and a critical callout. The length is justified by the tool's complexity, though the list of natural-language examples could be trimmed slightly without losing meaning. Overall, it is efficient and well-structured.

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

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

Given the tool's complexity (two pipelines, multiple verdicts, error semantics) and the absence of an output schema, the description is remarkably complete: it covers trigger scenarios, routing behavior, verdict vocabulary, return value structure (value + citation + reasoning), and the semantic distinction between could_not_verify and unsupported. This is sufficient for an agent to invoke the tool correctly without additional information.

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

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

The schema covers 100% of the two parameters with descriptions, and the description adds extra semantics: tolerance_pct overrides the claim-wording tolerance, defaults are capped at 5, and a claim is framed as a natural-language statement. The mention of 'exact percent-delta math' in the financial path further connects to tolerance behavior, providing 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 opens with multiple natural-language trigger phrases and defines the tool as 'natural-language claim verification against authoritative sources,' with a clear verb (verify) and resource (claims). It distinguishes itself from siblings by naming the two distinct pipelines (SEC EDGAR/XBRL for financial claims, grounded pipeline for others) and explicitly states it returns a verdict. This is a specific, unambiguous purpose.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a clear when-to-use condition. It also notes that it replaces 4–6 sequential calls, indicating when it should be used as a shortcut. However, it does not name alternative tools or provide explicit when-not-to-use guidance, 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.