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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior beyond that: question routing, automatic argument filling, structured answer format, and stable citation URIs. No contradiction exists between description and annotations.

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

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

The description is long but front-loaded with the key decision rule ('PREFER OVER WEB SEARCH') and then follows a logical structure: domains, mechanism, trigger phrases, examples, and sibling alternatives. Some lists are dense and slightly repetitive, but nearly every sentence contributes to correct tool selection and invocation.

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

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

Given the simple free-text input and the absence of an output schema, the description is highly complete: it explains what the tool returns, when to use it, when to use alternatives, and gives concrete examples. An agent has enough context to invoke this tool confidently and route edge cases to the appropriate sibling.

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

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

The input schema provides 100% coverage of the single logical parameter, including aliases (q, text, input, query, prompt, question). The description adds helpful example queries, but these mostly illustrate usage rather than providing new parameter-level semantics beyond what the schema already states.

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

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

The description clearly states what the tool does: it routes questions to 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes well beyond the tool name and title, and it differentiates ask_pipeworx from specialized siblings by presenting it as the default starting point.

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 'PREFER OVER WEB SEARCH' and gives concrete trigger phrases like 'what is', 'look up', 'find', 'get the latest', and 'current'. It also names alternatives: deep_research for robust multi-source reports, ask_pipeworx_grounded for citations/grounding, and ask_pipeworx_beta or bet_research for breaking news.

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 material behavioral context beyond the read-only annotations: the beta may change routing candidates live, no candidate is currently active, and this is a full working router with no fallback. This prevents the agent from assuming it is a stub or that a fallback to ask_pipeworx is needed. It does not contradict 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 longer than minimal but each sentence earns its place: beta status, identity with the stable tool, current active-candidate state, and routing comparison purpose. The key usage instruction comes near the end but is clearly marked ('Use it exactly like...'). No filler.

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

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

For a single-required-parameter router, the description covers current behavior, relationship to the stable version, experimental nature, and the absence of fallback. There is no output schema, but the description references the same response shape as ask_pipeworx, which is enough for selection. It could add an example question, but the schema already defines the input.

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 every alias (q, text, input, query, prompt, question) documented. The description adds only that the arguments are identical to ask_pipeworx, which is consistent but not additional semantic detail. Baseline 3 applies.

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

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

Clearly identifies the tool as a beta universal router with the same 5,798 tools and arguments as ask_pipeworx, so an agent knows it handles arbitrary questions by routing them. It distinguishes itself from ask_pipeworx by being the experimental edge with candidate routing improvements. A direct verb like 'routes' is implied by 'router' and 'use it exactly like ask_pipeworx'.

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

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

Explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It also states that when no candidate is active it matches ask_pipeworx exactly, telling the agent the behavior is the same right now. It stops short of listing when-not-to-use conditions, but the alternative is clear.

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

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

Even though annotations already mark it read-only and idempotent, the description discloses rich behavioral details: adherence to only tool-result content, a structured success response, explicit refusal reasons, and one extra LLM call as cost. There is no contradiction with the annotations.

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

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

The description is front-loaded with the primary purpose and every subsequent sentence adds actionable information. The return contract, refusal cases, and usage tradeoff are dense but each 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?

With no output schema present, the description fully specifies the success and refusal response shapes, and gives enough context for high-stakes vs casual use. Nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Input schema coverage is 100% and already describes the question parameter and its aliases, so the description needn't repeat them. The routing description adds context about how the question is processed, but no parameter-level semantics beyond the schema.

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

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

The description opens with a specific purpose — a hallucination-resistant answer mode for high-stakes reads — and differentiates itself from ask_pipeworx by stating it extracts answers using only the tool result contents. This tells an agent exactly what resource and behavior to expect.

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

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

It explicitly says when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also names the sibling tool it is compared to.

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?

The annotations already mark it read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: account/paid-tier requirements, parallel decomposition across 5,798 tools, gap reporting, contradictions() for standard/thorough, citation_uri fetchability semantics, and latency expectations. It also clarifies what it does not do (open-web search) and that it never invents missing answers.

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 content is informative but structurally bloated: the sentence 'For a single lookup use ask_pipeworx' is repeated dozens of times after already being stated once, which obscures the useful later details about hop behavior and contradictions. It is not front-loaded around the core purpose and much of the space is redundant.

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

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

With no output schema, the description compensates fully by enumerating the findings packet (verbatim evidence, confidence, source, fetched_at, citation URI), gap/contradiction fields, hop semantics, and expected runtime. It also covers access requirements and what data sources are searched, so an agent knows what to expect and what constraints apply.

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 both parameters at 100%, so the baseline is 3; the description adds value by defining depth levels ('thorough'=6 paid facets, 'standard'=3 default with gap recovery, 'quick'=3 single-hop) and by describing latency differences. The question parameter's natural-language and multi-part suitability is also reinforced with examples.

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 action — grounded multi-source research across 1517 structured data sources — and distinguishes it clearly from siblings: it explicitly says this is NOT open-web search and that single lookups should use ask_pipeworx. The examples ('compare X and Y's regulatory + financial exposure', 'research the filings + market picture for ACME') further anchor the tool's 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?

It gives explicit when-to-use rules: best for broad/multi-part questions over structured data, and not for single lookups ('For a single lookup use ask_pipeworx'). It also names the alternative for unsigned-in users, so an agent has concrete routing guidance rather than needing to infer from the name.

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?

Even though annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds meaningful behavioral detail: parallel fan-out across sources, USPTO soft-failure, expected empty FDA sections, sources_used/sources_failed semantics, GDELT-to-GNews fallback, and resolution behavior for private companies. It does not contradict 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 it is front-loaded with usage examples and the core promise before enumerating sources and output sections. Most clauses carry behavioral or routing information needed because there is no output schema. It could be tightened, but the density is largely justified.

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—ten sources, heterogeneous output sections, and no output schema—the description explicitly accounts for each returned section, section-specific failure modes, empty-data semantics, source fallbacks, and resolution failure for private companies. An agent has enough context to invoke it correctly and interpret the result.

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 already 100%, so the baseline is fair. The description still adds useful calling nuance: zero-padded CIK format, interchangeability of ticker/name/CIK, and the fact that `type` is purely a label with no behavioral difference. This goes beyond the schema without overstating new 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 names a specific resource (US public company) and a specific behavior (building a full cross-source profile in one parallel call), and opens with concrete query examples. It also distinguishes itself from single-pack lookups, making its role among sibling research tools clear.

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 ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups for holistic questions and gives many natural-language trigger examples. It does not explicitly compare against every potentially competing sibling such as deep_research or compare_entities, so a small routing ambiguity remains.

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 declare this read-only, idempotent, and non-destructive, so the description's added value is the lead-sponsor behavior and the source-scoped collection logic. It adds context about what is included/excluded beyond the annotations without contradicting them.

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

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

Three sentences with no filler: the first establishes purpose and sources, the second enumerates returns, and the third states the critical scope caveat. Every sentence carries essential information and the key distinction is front-loaded.

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

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

Even with no output schema, the description enumerates the three return categories in sufficient detail for an agent to judge fitness. It does not describe result shaping or pagination, but for a read-only catalyst-monitoring tool the core expectations are covered.

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 a 3 is the baseline. The description goes beyond the schema by clarifying that 'sponsor' means the named company as registered lead sponsor, not any organization using the product, and it contextualizes 'months_ahead' through upcoming and recently completed time horizons.

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 action ('Build a sponsor catalyst-monitoring view') and names its data sources, then itemizes the returned categories (upcoming Phase 2/3 primary-completion dates, recently completed trials, sponsor-linked FDA applications). The final sentence sets a precise boundary (company LEADS as registered sponsor) that distinguishes it from broader pipeline tools like 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?

It clearly frames the intended use case ('event-driven biotech research') and gives an explicit exclusion: trials run by another organization using the drug are not returned. It does not name a specific alternative tool, so it falls just short of full 5 guidance, but the context is not left to inference.

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

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

The annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds value by revealing the combined query behavior (true intersection count plus lead-sponsor tally) and the general output contents (phases, status, approvals). There is no contradiction with the annotations.

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

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

The description is three sentences with no unnecessary words. The first sentence states the primary function. The second lists what is returned. The third gives a specific combined-parameter example. Every sentence earns its place, and the structure is front-loaded for quick scanning.

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

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

Given the rich annotations and presence of an output schema, the description covers the essential behavioral aspects: search capability, output summary, and special combined-parameter handling. It does not discuss pagination, limits, or format details, but the output schema likely covers that, so completeness is 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 each parameter described individually. The description goes further by explaining how using status and phase together changes the output semantics (intersection count, tally). This interaction-level detail is not present in the schema and improves the agent's understanding of combined parameter use.

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

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

The description clearly states the tool searches clinical trials by condition or sponsor and returns phases, statuses, and approved treatments. However, it does not explicitly differentiate from sibling tools like pharma_pipeline_catalysts or pharma_indication_landscape, which could cause ambiguity for an agent deciding between 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 a concrete usage example for combined status and phase queries, explaining the special intersection + tally behavior. However, it offers no guidance on when to avoid this tool in favor of siblings (e.g., when a deep drug profile is needed) or when to use only condition vs. sponsor. The guidance is implicit rather than explicit.

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

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?

Even with readOnlyHint, openWorldHint, and idempotentHint already present, the description adds deep behavioral disclosure: compatibility_warning and compatibility_codes semantics, the meaning of null temporal_alignment, skipped_cross_type/subtype counters, unclassified legs never being paired, and the Kalshi fee caveat. This far exceeds annotation coverage and contradicts nothing.

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 and well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and no filler. It is quite long, and a few warnings (pre-mapped ≠ tradeable, temporal_alignment_unknown vs null alignment) are restated for emphasis, which keeps it just short of a perfect conciseness score.

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 full burden of explaining results, and it does so thoroughly: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility codes, temporal_alignment semantics, skipped counters, and fees_note. An agent has enough information to both call the tool and correctly interpret returned edge 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?

The input schema already documents all three optional parameters with examples and override semantics (100% coverage), so the baseline is 3. The description adds cross-cutting meaning beyond the schema: both modes run the identical matcher and the same disclosures apply, and it restates the full topic shortcut list. That incremental context justifies a 4.

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

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

The first sentence states a precise verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It then explains the computation (token-overlap matcher, spread in percentage points) and distinguishes itself from Polymarket-only siblings by emphasizing the cross-venue scope. The two operating modes are clearly part of the purpose.

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

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

The description gives clear guidance on when to use each mode: 'topic' for pre-mapped shortcuts and explicit ticker/slug for custom pairings, plus caveats like 'pre-mapped ≠ tradeable' and the gross-vs-net fee note. However, it never names sibling tools such as polymarket_arbitrage or states conditions for choosing them instead, so explicit alternatives/exclusions are absent.

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?

Even with readOnly/idempotent annotations, the description adds substantial context: graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous matches returning figi_candidates without asserting a result, source-labelled identifiers, and explicit unresolved fields. It also reveals that the call cascades through multiple lookup endpoints internally. No contradiction with annotations.

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

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

The description is long but densely informative, and it is front-loaded with user-like queries and the 'Use FIRST' directive before moving into type-specific details. A few example queries could be trimmed, but the verbosity is largely operational rather than filler.

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

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

With no output schema, the description compensates by specifying what is returned (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), how ambiguity is handled, how unresolved identifiers are surfaced, and what happens when upstream services fail. An agent has enough to invoke the tool and interpret its results correctly.

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

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

Although the schema already describes both parameters, the description adds high-value semantics beyond it: for value it instructs passing the ENTITY NAME ONLY, warns that trailing security-class words match nothing for bonds, and details accepted forms (ticker, CIK, ISIN, brand/generic name). This meaningfully prevents common agent errors.

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

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

The description names a specific action ('resolve a user-spoken NAME to the canonical/official identifiers') and a clear resource scope, and it distinguishes itself from sibling tools by positioning this as the first step that feeds 'other tools require as input'. It also enumerates supported entity types (company and drug) and gives concrete query examples.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and explains what kinds of inputs are acceptable. It does not explicitly name alternative tools or state when not to use this tool, so it misses the full when/when-not/alternatives guidance needed for a 5.

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

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

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.