Pharma Intel

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

Annotations already declare readonly/open/idempotent. Description adds return format (per-model objects + combined view) and cost implication for Anthropic calls. 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?

Three sentences, front-loaded with main purpose. Every sentence adds necessary information, 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?

Covers purpose, parameters, behavior, return format, and use cases. Adequate despite missing output schema; return format is described.

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: default model behavior, API key dependency, context disambiguation. Enhances understanding beyond schema.

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

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

Clearly states the action (probe/score) and resource (LLMs for a given entity). Distinguishes from sibling tools, none of which duplicate this functionality.

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?

Explains default model and optional Anthropic integration with BYO key. Provides use cases (AI-marketing audits, brand checks). Lacks explicit 'when not to use' but sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable context beyond annotations: it mentions routing behavior ('routes the question to the right one of 5,529 tools'), output format ('returns the structured answer with stable pipeworx:// citation URIs'), and default entry-point behavior. It doesn't dwell on rate limits or error cases, but for a read-only query tool the annotation coverage is strong.

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

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

The description is dense but well-structured: it opens with a directive ('PREFER OVER WEB SEARCH'), scopes the domain, explains routing, provides examples, and closes with escalation guidance. Every sentence adds value; there's no fluff or repetition of schema/annotation content. The use of examples and explicit 'START HERE' guidance makes it highly usable despite its length.

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

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

Given the tool's simplicity (one natural-language parameter, no output schema, read-only annotations), the description is remarkably complete. It covers when to use, what to expect (structured answer with citations), how to escalate to siblings, and provides multiple concrete examples. There are no missing pieces that would prevent correct invocation.

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

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

Schema description coverage is 100% (all six parameters are documented as aliases of 'question'), so the baseline is 3. The description confirms the parameter is a natural-language question and gives examples, but it doesn't add new parameter-level detail beyond the schema. It reinforces the semantics ('Your question or request in natural language') without introducing syntax or formatting constraints.

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 is extremely specific: it names the verb (ask/routes), the resource (a collection of 5,529 tools across 1,455 verified sources), and the scope (current or historical real-world data with citations). It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point for most factual 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 explicitly states when to use this tool ('START HERE', 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...'), provides concrete example queries, and names alternatives for specific cases ('Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for broad/multi-part questions... use deep_research'). This goes beyond mere context and provides actionable when/when-not 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?

Beyond the annotations (read-only, idempotent, open-world), the description discloses that this is experimental, may have live routing improvements under test, is currently idle, and behaves identically to the stable router. It also clarifies it is a full working router, not a fallback, which adds valuable context.

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

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

The description is composed of three informative sentences, front-loaded with the beta identity, then current state, then usage guidance. While some details (e.g., 5,529 tools, exact date) add length, each sentence provides distinctive context and the structure is logical.

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 no-output-schema tool, the description is thorough: it covers purpose, usage, experimental nature, current parity with stable, and relationship to sibling tools, even confirming the same response shape. Combined with annotations, the agent has a complete picture.

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 parameters, all documented as aliases for 'question'. The description adds no new parameter details beyond referencing 'same arguments' as ask_pipeworx, so the schema carries the semantics. 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 identifies the tool as the beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable variant and related siblings. The verb 'ask' and the router framing make the purpose unambiguous.

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

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

It explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router, implying when not to use it (when stability is preferred). This is direct 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses that the tool costs an extra LLM call, returns a structured refusal with specific reasons when the data doesn't answer, and extracts answers using only the tool result to prevent hallucination. This is rich behavioral context that annotations do not provide.

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

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

The description is front-loaded with a one-line summary and then packs high-value details (return shape, refusal reasons, use cases, cost) into a compact, well-structured paragraph. Every sentence contributes meaningful information; there is no filler or redundancy.

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

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

For a read-only QA tool with a single real parameter, the description is complete: it explains what the tool does, when to use it, what it returns on success and failure, and its cost. The schema covers parameters, annotations cover safety, and the output schema is absent but the description details the return format and refusal reasons, leaving no major 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 schema covers all 6 parameters (all aliases for 'question') with 100% coverage, so the baseline is 3. The description does not add any parameter-specific semantics beyond what the schema already provides, which is acceptable given the high coverage.

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

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

The description states a specific purpose: 'Hallucination-resistant answer mode for high-stakes reads' and clearly differentiates from the sibling ask_pipeworx by describing the extraction-with-evidence and refusal behavior. The verb 'extracts' and the resource 'answer' are explicit, making the tool's function 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?

It explicitly instructs when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and contrasts it with the alternative: 'prefer ask_pipeworx for casual lookups.' It also names the exact tool as the alternative and mentions the cost trade-off, giving clear when-to/when-not-to 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: resolver contract with confidence levels, parent event extraction, news fallback handling, safety short-circuits for low confidence and closed markets, wide spread warnings, and resolution-rule risk analysis. 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 very long but well-structured with clear sections. It covers many details, but conciseness suffers. Front-loading is decent with purpose first, but the length could be trimmed without losing value.

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

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

Given the complexity of the tool (multiple edge cases, resolver, parent events, news fallback, spread warnings, cancellation rules), the description is thorough. It explains return shapes, error states, and blocking conditions. No output schema exists, so description compensates fully.

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 good descriptions for all three parameters. The description does not add significant extra meaning beyond the schema's parameter descriptions, 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?

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'research' and the resource 'a Polymarket bet'. It distinguishes from siblings by focusing on individual bet research vs. general queries or edge scanning.

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

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

The description explicitly says to use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It provides clear use cases but does not explicitly state when not to use it, though context with sibling tools implies exclusions.

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

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

Adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL, FAERS), handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. No contradiction with annotations.

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

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

Two efficient sentences: first covers use cases and alternatives, second covers type-specific behavior. Every sentence adds value; no fluff.

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

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

Given the tool's complexity (2 entity types, 2 parameters, no output schema), the description is complete. It details what data is returned, how results are sorted, and that citations are included.

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

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

Adds meaning beyond the input schema: explains what data each type pulls (revenue/net income/cash/debt for companies, adverse events/approvals/trials for drugs) and gives concrete examples for parameter values.

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

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

The description clearly defines the tool's purpose as a side-by-side comparison of 2-5 entities (companies or drugs) with specific financial or adverse event metrics. It distinguishes itself from sibling tools like entity_profile and pharma_* tools by emphasizing parallel lookup over sequential.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. Clear when to use and that it replaces 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: account/tier requirements, output format (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), explicit gaps[] that are never invented, contradictions[] for standard/thorough, semantic excerpting instead of head-truncation, and expected latency (15-60s, ~90s for thorough). This goes well beyond the annotations.

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

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

The description is long but every sentence earns its place: account prereqs, functional description, when-to-use, output fields, limitations, latency, and depth semantics are all covered without redundancy. The structure is front-loaded with the most critical operational detail (account needed and fallback) and flows logically into capabilities and edge cases. It is appropriately sized for a tool of this 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?

There is no output schema, so the description carries full responsibility for explaining return values. It thoroughly covers the findings packet (evidence, confidence, source, fetched_at, citation_uri, hop field, gaps[], contradictions[]), edge cases (structured-catalog only, not news), semantic excerpting, and expected latency. It even notes that citations are always fetchable via resources/read, making the tool self-contained and actionable.

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 100% of parameters with descriptions, but the description adds crucial meaning: it explains that 'quick'='3 facets', 'standard'='5 facets with gap-recovery + contradictions', and 'thorough'='8 facets with iterative leads + contradictions' (and paid). It also clarifies the question parameter by saying 'Broad/multi-part is fine — decomposition is the point', enriching both params 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources in ONE call', and further details how it decomposes questions and routes to 5,529 tools in parallel. It explicitly distinguishes itself from sibling tools like ask_pipeworx, stating it is NOT open-web search and is best for broad/multi-part structured-data 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' vs. 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides a fallback if not signed in and explains depth tiers for iterative research, making alternatives and exclusions crystal clear.

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

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

Annotations already indicate safe, idempotent read-only behavior. The description adds significant behavioral context: it explains the return format ('top-N most relevant tools with names, descriptions, and full input schemas') and emphasizes that results are 'ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

The description is a single paragraph of moderate length. It front-loads the purpose and provides useful details without unnecessary verbosity. Some structure (e.g., bullet points for the list of domains) could improve scannability, but it remains concise and informative.

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

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

Given the tool's complexity (multiple aliases, no output schema), the description adequately covers behavior and output format. It explains that the tool returns 'full input schemas (with curated examples),' which is sufficient for an agent to use the results. No critical gaps remain.

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

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

Schema description coverage is 100%; all parameters are documented with aliases. The description adds minimal extra meaning beyond the schema; it mentions 'query' implicitly but does not describe the aliases or the limit parameter in detail. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the verb ('discover'), the resource ('tools'), and the context ('by describing the data or task'). The list of example domains further clarifies its scope, distinguishing it from sibling tools that perform specific analyses or retrievals.

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 recommends using this tool first: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use it. While it does not explicitly state when not to use it, the context implies it is for exploration, not direct answers.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. Description adds behavioral details: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, mentions soft-fail for patents sunset, and clarifies error handling. No contradictions.

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

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

Description is front-loaded with example queries and purpose, then lists return data and limitations. Though slightly verbose, every sentence adds value. Could be more concise but still well-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?

Given the tool's complexity (multiple data sources), the description covers input requirements, output fields, limitations (patents sunset, no name support), and usage hints. No output schema, but return values are described adequately. The description sufficiently qualifies the tool's context.

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

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

Schema covers both parameters with descriptions (100% coverage). Description reinforces the meaning: ticker or zero-padded CIK, and reiterates that names are not supported, adding the context to use resolve_entity. This extra context justifies above baseline 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?

Description clearly states the tool provides a full cross-source profile of a US public company, with example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes from sibling tool resolve_entity by noting that names are not supported and should be resolved first.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint: true and idempotentHint: true. Description adds context on when to delete but no additional behavioral traits beyond what annotations convey.

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

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

Two sentences, front-loaded with action, 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 1-param tool with no output schema, description is complete: action, usage, and pairing with siblings.

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

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

Schema coverage is 100% with the single 'key' parameter described. Description does not add extra detail beyond the schema.

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

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

The description explicitly states 'Delete a previously stored memory by key', with specific verb (delete) and resource (memory). It also distinguishes from siblings 'remember' and 'recall'.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting markdown. It also specifies the output format and placement, which is valuable beyond annotations.

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

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

The description is concise with two main sentences and a bullet list of use cases. It is front-loaded with the core action and every sentence contributes meaningful information 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?

While there is no output schema, the description explains the output as a single text blob ready for deployment. It covers the process and purpose. Missing error handling details but acceptable given the simplicity and strong annotations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default and maximum for 'max_links', which is not in the schema. This extra context helps the agent choose appropriate values.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, with specific verb 'generate' and resource 'llms.txt file'. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on outputting the standard markdown file.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitors. However, it does not mention when not to use it or provide direct comparisons with sibling tools, leaving some ambiguity.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return field details but no extra behavioral traits 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, front-loaded with purpose and return fields, usage guidance included. No extraneous content.

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

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

Simple tool with one optional parameter, return fields listed, annotations cover safety. Description is complete 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 a single boolean parameter description. Description does not add meaning beyond schema.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies return fields. It 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?

Explicit guidance: use to review monitoring before adding more or to find an id to cancel. Implies when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds behavioral context by listing the types of data returned (approval dates, formulations, interactions, trial details), which is useful beyond the annotations. No contradictions.

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

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

Two sentences with an example, no wasted words. Front-loaded with key actions and data types. 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 the output schema exists, the description does not need to explain return values. It covers the main categories of data (approval, dosage, interactions, trials) and provides examples. It is reasonably complete for a lookup tool.

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

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

Schema coverage is 100%, so the parameter is fully documented in the schema. The description does not add extra meaning beyond the schema's description ('Drug name (brand or generic)'), but the examples provide practical guidance. 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 the tool looks up FDA approval status, dosage forms, interactions, and active trials, with examples. It specifies the resource (drug) and the verb (look up). However, it does not explicitly differentiate from sibling pharma tools like pharma_pipeline_catalysts or pharma_safety_report, which is a minor gap.

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

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

The description implies usage for looking up drug profiles and provides example queries ('ozempic', 'metformin'), but it does not explicitly state when to use this tool versus alternatives. No when-not-to-use or exclusion criteria are mentioned.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context on data sources (trials, FDA labels, PubMed) and the shape of returned evidence, enriching the behavioral model without contradicting annotations.

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

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

Two focused sentences with no filler. The first sentence states the action and sources; the second lists outputs. All content earns its place.

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

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

For a 2-parameter read-only research tool with no output schema, the description covers the main inputs, process, and return fields. It could mention pagination or result size limits, but the core use is clear. Annotations fill the remaining safety context, making this 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 both parameters described ('Disease or condition.' and 'Optional drug, modality, or intervention filter.'). The description does not add extra parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Build a disease-area landscape' with specific data sources (registered interventional trials, FDA indication-label matches, PubMed literature) and output fields (sponsor, phase, status, intervention, approved-label, publication evidence). This distinguishes it from sibling pharma tools like pharma_drug_profile or pharma_pipeline_scan.

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

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

The description implies usage for indication research and outlines what it aggregates, but it does not explicitly name alternative tools or exclusion criteria. Since the context is clear but no 'when not to use' is provided, it earns a 4.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, lowering the burden on the description. The description adds context about data sources and return categories, but it does not disclose potential limitations, response shape, or any special behavioral nuances beyond what annotations cover.

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

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

The description is a single, dense sentence that front-loads the core verb and resource, then lists the specific return items. Every phrase contributes information, with no filler or redundancy.

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

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

Given no output schema, the description adequately explains the main return values: upcoming primary-completion dates, recent trial results, and FDA applications. It is complete enough for an agent to choose and invoke the tool, though it does not detail output format or pagination, which could matter for complex integration.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'sponsor' implicitly but adds no new meaning beyond the schema for either parameter; months_ahead is only described in the schema. The schema carries the parameter documentation burden.

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 ('Build') and names distinct resources ('ClinicalTrials.gov and Drugs@FDA'), with a clear output scope: sponsor-linked Phase 2/3 completions, recent trial results, and FDA applications. It is specific enough to distinguish from sibling tools like pharma_pipeline_scan or pharma_sponsor_diligence.

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

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

The description clearly implies the tool is for event-driven biotech research and sponsor catalyst monitoring, which is a clear use context. However, it does not explicitly state when not to use this tool or name an alternative, so it stops short of full 5-level guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing what the tool returns (trial phases, recruitment status, approved treatments), going beyond the annotation safety profile.

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

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

Two sentences, no fluff. Front-loaded with action and resource, then output. 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 an output schema exists, the description adequately explains what is returned. The two parameters are covered with examples, and the tool's context is complete for a search 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?

Both parameters have schema descriptions (100% coverage), so the description doesn't add new semantic meaning. It reinforces with examples but does not exceed the schema baseline.

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

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

The description clearly states the tool's purpose: 'Search clinical trials by condition or sponsor' and specifies the output (trial phases, recruitment status, approved treatments). This distinguishes it from siblings like pharma_drug_profile or pharma_safety_report.

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

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

The description implies usage for clinical trial search but lacks explicit guidance on when to use this tool vs alternatives or when not to use it. No exclusions or sibling comparisons are provided.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds that it returns safety profiles, risk data, and recall history, which supplements but does not significantly extend beyond what annotations convey.

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

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

Two concise sentences with an example. Front-loaded with the core action and returns. No superfluous text.

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 param, output schema present), the description covers purpose, returns, and provides an example. It is fully adequate for an agent to understand and invoke the tool.

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

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

Schema coverage is 100% with a clear description for 'drug_name'. The description reinforces with an example but adds no extra semantic nuance 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: checking adverse event frequency, severity patterns, and contraindications for a drug. It uses a specific verb ('check') and resource ('adverse events') and distinguishes itself from siblings like 'pharma_drug_profile' by focusing on safety 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 implies usage for safety-related queries about a drug but does not explicitly mention when to avoid using it or provide alternatives among siblings. The example hints at common use but no direct 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, and non-destructive behavior. The description adds value by naming the integrated sources and specifying the returned components (pipeline composition, registry activity, FDA applications, literature). No contradiction with annotations.

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

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

The description is two sentences with no fluff: first sentence states the action and sources, second lists outputs. Front-loaded 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?

With no output schema, the description carries the burden of explaining return values and does so by listing four output categories. It also mentions the three data sources. While some terms like 'pipeline composition' are implicit, the description is adequate for a sponsor-research tool.

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

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

Schema description coverage is 100%: both 'sponsor' and 'since' have clear descriptions, including the default for 'since'. The description does not add parameter details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool builds a 'pharmaceutical sponsor diligence view' from specified sources (ClinicalTrials.gov, Drugs@FDA, PubMed) and lists concrete output categories. This distinguishes it from sibling tools like pharma_drug_profile or pharma_indication_landscape by focusing on sponsor-level company research.

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

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

The phrase 'for company research' provides clear context for when to use this tool. However, it does not explicitly mention alternatives or exclusions relative to sibling tools, so it falls short of full 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 discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token round-trip for reading resolution status, daily digest behavior, and the fact that it's free and doesn't count against quota. These go well beyond the sparse all-false annotations and give the agent accurate expectations.

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

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

Although longer than average, every sentence earns its place: purpose, when to use, when not to use, what to write, token mechanics, throughput limits, and cost. It is front-loaded with the core purpose and structured for quick scanning.

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

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

With no output schema, the description compensates by explaining the claim_token return value and resolution flow. It covers prerequisites, exclusions, message guidelines, rate limits, and parameter interplay, making the tool fully self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by explaining the claim_token round-trip ('Filing without an account returns a claim_token; pass it back later...') and explicitly tying the type enum values to real-world situations, which helps the agent choose the right enum value.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from siblings by explicitly stating it is only for tools served by this Pipeworx connection and naming alternative servers for unrelated 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?

Usage is explicitly tied to triggers: bug, feature/data_gap, praise. It also gives a clear when-not-to-use: if the tool came from a different MCP server, file with that server instead. This is a model of explicit 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds caching details (5min-1h) and data origin (CF analytics-engine, no PII), providing useful behavioral context beyond annotations.

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

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

The description is concise, front-loaded with the primary function, and uses bullet points for clarity. Every sentence adds value without redundancy.

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

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

Although there is no output schema, the description specifies the return components (top tools, top packs, total call volume). It also mentions caching and data source. For a lightweight trending tool, this is sufficiently complete.

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

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

The single parameter 'window' has a schema enum with descriptions, and the description further clarifies the implications: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds significant meaning.

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

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

The description clearly states it returns trending data: 'top tools, top packs, and total call volume' over a selectable window. It distinguishes from sibling tools like 'ask_pipeworx' (querying) and 'discover_tools' (discovery) by focusing on aggregate popularity signals.

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 three concrete use cases (discovering hot sources, confirming canonical choice, aligning with agent needs). While it doesn't explicitly state when NOT to use, the scenarios effectively guide selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: response structure, fill check details, semantic anchor (Jaccard similarity), partition filter, and trading signals. No contradictions with annotations.

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

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

While the description is well-structured and front-loaded with the core purpose, it is quite verbose (multiple paragraphs with detailed explanations of internal logic, fill checks, and filters). Some details could be truncated or moved to a more detailed documentation, making it less concise than ideal for a tool description.

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

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

The description is remarkably comprehensive given the tool's complexity and the absence of an output schema. It explains the return structure (opportunities array with gap_pp, suggested_trade, reasoning), the fill check mechanism, and edge cases like placeholder filters. No gaps left for an agent to guess.

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

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

Schema description coverage is 100% (both event and topic have descriptions). The description adds value by explaining the semantic meaning (e.g., event slug vs. topic seed question) and noting that full Polymarket URLs are also accepted for event param. This goes beyond the schema's bare 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 purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three distinct modes (no-args, event, topic) with clear differentiation, making it distinguishable from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: no-args for trending scan, event for a specific market, topic for cross-event scanning. It explains why topic mode catches patterns missed by single-event mode. While it doesn't list explicit when-not-to-use scenarios, the context is sufficient for intelligent 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?

The description extensively discloses behavioral traits: response segmentation, caching at KV level (1h), diagnostics for empty segments, Fed bets exclusion rationale, and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint; the description adds rich context 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 excessively long and verbose, containing technical minutiae (e.g., specific Kelly caps, α values, placeholder filters) that could be abbreviated. While front-loaded with purpose, the density of details reduces readability. A more concise version would retain 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?

Despite the lack of an output schema, the description thoroughly explains the response structure, including field names, segments, diagnostics, and edge cases (empty segments, Fed bets). It covers caching, knobs, and per-opportunity attributes, making the tool's behavior fully understandable for an agent.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds minor contextual reinforcement (e.g., 'tradeable-edge filter' for max_spread_pp and min_liquidity) but does not introduce new information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly targets the 'what should I bet on today' use case and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on Pipeworx-specific edge detection.

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

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

The description provides context for when to use the tool—discovering betting opportunities across three model families. It explains tradeable-edge knobs but does not explicitly contrast with siblings or state when not to use it. The guidance is clear but lacks 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?

The description extensively explains behavior beyond annotations: it reads from daily snapshots, computes time-series, trend, decay rate, and expired opportunities. It also clarifies that decay numbers come from daily closes, not intraday. No contradictions 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?

The description is lengthier but well-structured: starts with purpose, then parameters, then detailed response format, then limits. Every sentence adds value, though some redundancy could be trimmed. It is front-loaded with the key question.

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 of time-series analysis and no output schema, the description completely explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, snapshot start). Provides all necessary context for an agent to use 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?

Both parameters have schema descriptions, but the tool description adds context: specifies defaults (days=14, window='1wk'), explains 'window' as a snapshot family, and lists options. This adds meaning beyond the schema alone.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering a specific question about edge duration and shrinkage. The verb is implied as 'track' and the resource is well-defined, 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 explicitly frames the tool around answering 'how long has this edge existed and is it shrinking?' with an example contrasting fresh vs old edges. It provides context on when the tool is useful but does not mention alternatives or when not to use it. The LIMITS section adds clarity on history depth.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds behavioral detail about walking the order book ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, and verdict, which goes beyond what annotations provide.

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

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

The description is longer than ideal but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the purpose and uses clear headings. While every sentence adds value, some redundancy could be trimmed, but overall it is efficient for the complexity.

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

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

Given the tool's complexity (two modes, multiple output fields), the description is comprehensive. It explains both single-market and basket modes in detail, lists the outputs for each, and addresses practical concerns like forced directional risk and partial fills. No output schema exists, so the description fully covers return values and behavior.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning: it explains the interpretation of size_usd for single-market vs basket modes, clarifies side defaults, and elaborates on basket mode parameters (e.g., theoretical_sum vs realizable_sum). This extra context raises the score.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order book depth, distinguishing between single-market and basket modes. It differentiates itself from sibling tools by explicitly instructing to use this before acting on polymarket_arbitrage or polymarket_edges signals, making its purpose unique and specific.

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

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

The description provides explicit guidance on when to use this tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also warns about the risks of not using it (partial fills converting arbs into unhedged directional positions), establishing clear usage context and exclusions.

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

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

Annotations already show readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral details: response format, safety fields, temporal alignment, skipped cross types, and the caveat that pre-mapped ≠ tradeable. 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 with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though some redundancy exists (e.g., repeated warning about pre-mapped topics). Front-loaded with purpose.

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

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

Despite no output schema, the description fully explains the response structure, edge cases (matched_pairs=0, skipped cross counters, temporal alignment flag), and data meaning. Sufficient for an agent to understand inputs, outputs, and potential issues.

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 all 3 parameters with descriptions. The tool description adds extra meaning by enumerating topic shortcuts, explaining overriding behavior, and providing example values. Schema coverage is 100%, so baseline 3, but the description significantly enriches 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 computes cross-venue spreads between Kalshi and Polymarket, describes two modes (topic shortcuts and explicit tickers), and distinguishes it from siblings like polymarket_arbitrage by focusing on venue 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?

Explicitly describes when to use topic mode vs explicit mode, warns about compatibility issues and temporal misalignment, and advises that pre-mapped topics often return warnings. Lacks direct alternatives but covers usage context well.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds behavior: omitting key lists all keys, scoped to user identifier, pairs with remember/forget. No contradictions.

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

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

Three sentences, front-loaded with main action, every sentence adds value. No redundancy.

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

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

Comprehensive for a simple retrieval tool: explains key parameter, listing behavior, scoping, and pairing with siblings. Output schema not 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?

Single parameter 'key' with schema coverage 100%. Description adds meaning: 'omit to list all keys'. Provides examples in 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 states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' Clearly distinguishes from siblings like remember and forget.

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

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

Explicitly says when to use ('Use to look up context the agent stored earlier... without re-deriving it from scratch') and scoping ('Scoped to your identifier'). Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable detail about mark_read behavior (flagging events read) and return fields (source, citation_uri, payload), which goes beyond annotations.

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

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

Four sentences, each with distinct purpose: main action, return fields, filters, state mutation, and alternative access. No fluff; optimally 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?

Despite no output schema, description clearly explains return structure (source, citation_uri, raw payload). All optional parameters are outlined with their effects. Complete for a read-only polling tool with good annotations.

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

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

Schema covers all 5 parameters with descriptions (100% coverage). Description briefly reiterates 'type', 'since', and 'mark_read' but adds little extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states 'Pull fired events from your subscription feed' with specific verb 'Pull' and resource 'fired events'. Distinguishes from siblings like list_subscriptions by focusing on recent alerts from the feed.

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

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

Provides context for polling and mentions an alternative REST endpoint for scripts/dashboards. Lacks explicit when-not-to-use instructions but gives adequate 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), description adds fan-out to multiple sources, fallback behavior, parameters (ISO/relative date), and return format (changes grouped by source with citations). No contradiction.

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

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

Description is front-loaded with query examples and efficiently organized: examples, mechanics, fallbacks, parameters, return hints, sibling reference. However, it is somewhat verbose; could be tightened without losing clarity.

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

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

Given no output schema, description adequately hints at return format (structured changes grouped by source, total_changes count, citation URIs). It also notes soft-fail for USPTO. However, it omits what happens on empty results or error states.

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. Description adds value by giving relative shorthand examples ('7d', '3m'), suggesting '30d' or '1m' for typical monitoring, and clarifying 'type' only supports 'company'. Not a 5 because schema already covers basics well.

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

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

Description clearly states it provides a change feed for a company, given example queries like 'What's new with X' and explicitly distinguishes from sibling 'entity_profile'. Verb+resource+scope are specific and non-tautological.

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 tells when to use (for recent changes) and when not to use (use entity_profile for static profile regardless of window). Also provides fallback logic (GDELT→GNews) and soft-fail for USPTO.

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 (idempotentHint=true, destructiveHint=false) are consistent. The description adds context about scope (scoped by identifier) and persistence differences (authenticated vs anonymous sessions, 24-hour retention).

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 (4 sentences), front-loaded with purpose, and every sentence adds necessary context. No wasted words.

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

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

Given no output schema, the description effectively pairs the tool with recall and forget, and provides sufficient behavioral context. However, explicit mention of overwrite behavior could further enhance completeness.

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

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

Schema already provides descriptions for key and value (100% coverage). The description adds value by giving example key patterns (e.g., 'subject_property') and clarifying value types (findings, addresses, preferences, notes).

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

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

The description clearly states that the tool saves data for later reuse across conversations or sessions, with specific examples (resolved ticker, target address, user preference). It 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?

Provides explicit guidance on when to use: when discovering something worth carrying forward, and mentions alternatives (recall to retrieve, forget to delete), helping the agent decide between tools.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing internal cascading lookups, graceful degradation for LEI/FIGI enrichment, source labeling for each identifier, and explicit reporting of unresolved identifiers under `unresolved`. These details are critical for an agent to anticipate behavior.

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

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

The description is longer than ideal but well-structured: it opens with example triggers, then a concise purpose statement, then detailed per-type breakdowns. Each sentence adds substantive information, though it could be tightened slightly without losing value.

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

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

The description is exceptionally complete for a tool with no output schema. It covers purpose, usage, input forms, return contents (identifiers, sources), failure handling, and relationship to other tools. The depth is appropriate 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 input schema already fully describes both parameters with examples (100% coverage), so the baseline is 3. The description reiterates accepted input forms for each type but does not add new parameter-specific meaning 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 is explicit and specific: it opens with example queries ('What's the ticker for…', 'find the CIK for…') and clearly states it 'resolve[s] a user-spoken NAME to the canonical/official identifiers other tools require as input.' This distinguishes it from sibling tools that consume identifiers rather than resolving 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 guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists supported entity types and accepted input forms. However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a perfect score.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: it internally calls 'ai_visibility_check' per entity, treats the first entity as the subject, and returns a ranked list with score, confidence, and signal density. It also notes that the 'anthropic' model requires an API key. These enrich the agent's understanding of what the tool does without contradicting 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 extremely concise: 4 sentences that front-load the primary action, explain the mechanism, provide a concrete use case with an example, and summarize the output. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's complexity (4 parameters, no output schema), the description adequately explains the input semantics and output structure ('ranked list with score, confidence, signal density'). It mentions the entity count limit and the optional API key. The only gap is the lack of explicit error handling or edge case behavior, but this is acceptable for a comparison tool with clear annotations.

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

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

While the input schema covers all 4 parameters with descriptions (100% coverage), the description adds context that the 'entities' parameter's first entry is treated as the subject and the rest as competitors. It also explains the purpose of the 'context' parameter (disambiguation) and the 'models' parameter (probe options). This goes beyond the schema alone and helps the agent use the parameters correctly.

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 ('Compare', 'Probes', 'ranks', 'surfaces') and clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies most/least recognized. It explicitly distinguishes itself from the sibling 'ai_visibility_check' by framing it as a multi-entity comparison tool, and the example quote reinforces the competitive audit use case.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question, helping agents know when to invoke this tool over alternatives. However, it does not explicitly state when NOT to use it or mention the related sibling 'compare_entities', which could be a potential alternative. The guidance is strong but not exhaustive.

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 partial failure behavior ('bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns') beyond what annotations provide. Annotations already mark it as readOnly, openWorld, idempotent, not destructive, and the description adds operational nuance.

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

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

Description is well-structured with front-loaded purpose, but includes an aside about other ecosystems that could be trimmed. Still efficient and clear.

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

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

Given no output schema, the description details the return structure (summary block, per-advisory detail, links, alternative versions). Covers edge cases (partial failures, ecosystem limitation, timing) and provides all necessary context for agent invocation.

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

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

Schema covers both parameters with descriptions. Description adds value by noting scoped packages are accepted and that version defaults to latest published. While schema is 100% covered, the extra context elevates it above baseline.

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

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

The description uses specific verbs and resources: 'composite ... check', 'fans out across deps.dev and bundlephobia', and explicitly states the question it answers ('is X safe / popular / small'). It distinguishes itself from sibling tools by focusing on npm packages and using specific data sources.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also defines ecosystem scope ('NPM ecosystem only in v1') and points to alternatives for other ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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 safety (readOnlyHint, idempotentHint), but the description adds critical details beyond them: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), input cap (200K chars), truncation behavior with flagging. 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?

Two well-structured sentences with front-loaded purpose and benefits. Uses formatting (bold, dashes) for readability. Every sentence adds unique information; no redundancy. The technical note at the end efficiently summarizes embedding details.

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

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

Despite lacking an output schema, the description fully explains return format (passages with offsets and similarity scores), internal mechanics (embedding, chunking, cap, truncation), and integration with a sibling tool. An agent has all needed information to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by noting that longer inputs are truncated and flagged (not in schema), and provides natural-language query examples similar to schema but in a more contextual sentence. This justifies a 4.

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

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

Clearly states "semantic search INSIDE a fetched record" with a specific verb and resource. Distinguishes from siblings by positioning as a targeted search within a specific record, contrasting with general search or grounding tools. Examples like SEC 10-K and pairing with ask_pipeworx_grounded reinforce its unique role.

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

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

Explicitly says when to use: "Use when the record is too big to cram into the prompt." Provides key benefits (saves context, returns only relevant passages with offsets) and names an alternative (ask_pipeworx_grounded) for grounding. This gives clear guidance on context and alternatives.

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

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

The description discloses important behavioral traits beyond annotations: it returns a subscription id, requires OAuth, notes SMS caps and phone verification, explains webhook auto-disable after failures, and details delivery constraints. Annotations 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 well-structured: purpose first, then requirements, then type definitions, then delivery. It is somewhat long but every sentence adds value, and it is front-loaded with the core purpose.

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

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

Despite no output schema, the description covers all necessary context: prerequisites, all subscription types and their parameters, delivery options with constraints, rate limits, and error states. 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?

With 100% schema coverage, the baseline is 3, but the description adds extensive meaning to each parameter: it explains type-specific params, delivery channel details, SMS cap, phone verification, and webhook signing. This far exceeds 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 the purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It uses a specific verb ('Create') and resource ('subscription'), distinguishing it from sibling tools like list_subscriptions 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 provides good usage context, mentioning the requirement for a Pipeworx OAuth account and giving examples of supported types and delivery channels. However, it does not explicitly state when not to use this tool or mention alternatives like recent_alerts for pull-based access.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about returning example questions with tool shapes and being the onboarding entry point, but does not contradict annotations.

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

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

Slightly verbose due to listing many categories and examples, but front-loads key purpose and usage. Each sentence adds value without redundancy.

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

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

For an onboarding tool, the description is comprehensive: explains what it returns, how to filter, and when to use it. Despite no output schema, the description adequately covers return format and use cases.

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

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

Schema coverage is 100%; the single 'topic' parameter is described in schema. Description adds behavioral nuance: 'Call with no arguments for the full spread' and enumerates topic values, reinforcing 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 states the tool's purpose: returns category-bucketed example questions for Pipeworx, acting as an onboarding entry point. It distinguishes itself from siblings by specifying its use case and the scope of 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?

Explicitly advises using this tool FIRST when unfamiliar with Pipeworx, and provides alternatives by mentioning meta-tools and topic filtering. 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 that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This adds behavioral context beyond the annotations (idempotentHint=true). 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?

Two sentences, no wasted words, front-loaded with the core action. Efficient and easy to parse.

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

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

Fully covers the tool's purpose, effect, ownership rule, and data handling. No output schema needed given the simplicity. Complete for a one-parameter mutation tool.

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

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

The description adds context to the id parameter beyond the schema's own description, specifying it is 'returned by subscribe' and referring to it as 'by id'. With 100% schema coverage, this extra linkage adds value.

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

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

Clearly states the action 'Cancel a subscription by id', specifies the target resource (subscription), and adds nuanced context about ownership enforcement. Distinguishes well from sibling tools like subscribe and list_subscriptions.

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

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

Provides an explicit constraint: 'you can only cancel your own subscriptions'. While it doesn't explicitly say when not to use or name alternatives, the constraint is clear enough for most use cases. Could be improved by referencing when to use subscribe or list_subscriptions instead.

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

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

The description reveals important behavioral details beyond the annotations: it defines the verdict types, distinguishes 'could_not_verify' from 'unsupported', mentions verification_error with stage/detail, and explains exact percent-delta math and verbatim evidence with citations. This adds substantial non-obvious context that the annotations (readOnlyHint, openWorldHint, idempotentHint) do not cover.

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

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

The description is long but information-dense, front-loaded with trigger phrases and usage context. It includes essential caveats (could_not_verify vs unsupported) and replacement semantics, all of which earn their place. It could be slightly more concise by trimming some repetitive examples, but overall it is 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?

Despite lacking an output schema, the description thoroughly explains return values (verdict types, actual value, reasoning, citation) and error handling (verification_error). It covers routing logic and edge cases, making it fully complete for a 2-parameter tool with no output schema.

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

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

The input schema already provides 100% coverage of both parameters, with detailed descriptions and examples for claim and tolerance_pct. The description does not add additional parameter-level meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific verbs like 'fact check' and 'verify'. It distinguishes itself from siblings by describing the two-path routing (SEC EDGAR for financial claims, grounded pipeline otherwise) and noting it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It gives clear context for when to use the tool, but does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions.

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