Chembl

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds context about the return content (IC50/Ki/EC50 values, assay descriptions, units), which is useful beyond annotations. However, it does not disclose pagination behavior, default limits beyond schema, or any other operational quirks. With strong annotations, the added value is moderate, warranting a 3.

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 sentence, front-loaded with the verb 'Retrieve', and contains no filler. Every element—resource, filters, and return types—serves a purpose. It is concise and well-structured, earning a 5.

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

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

For a tool with no required parameters, good annotations, and an output schema, the description covers the essentials: what it does, filtering options, and return content. It lacks explicit explanation of how the two filters interact (e.g., logical AND when both are provided), but the phrase 'and/or' addresses this ambiguously. The output schema likely fills return-value details, so the description is sufficiently complete for a tool of this simplicity. A 4 captures the slight gap in exact filter 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 only 33% (only 'limit' has a description). The description compensates by explicitly naming molecule_chembl_id and target_chembl_id as filter criteria and clarifying they can be used in combination ('and/or'). This adds meaning to two otherwise undocumented parameters, going beyond the schema. The 'limit' parameter is adequately described in the schema, so no additional semantics are needed there.

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

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

The description states a specific verb ('Retrieve') and resource ('bioactivity records from ChEMBL'), with concrete filtering attributes (molecule_chembl_id, target_chembl_id) and return content (IC50/Ki/EC50 values, assay descriptions, units). This clearly distinguishes it from sibling tools like molecule or target, which focus on entities rather than activity records.

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

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

The description gives clear context for when to use the tool: when bioactivity records filtered by molecule or target ChEMBL IDs are needed. It does not explicitly mention alternatives or when not to use it, but the specificity of the filtering criteria implies the appropriate use case. A 4 is justified over 5 due to the absence of explicit exclusions or alternative tool references.

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 describing read-only and idempotent behavior, the description adds cost transparency ('you pay Anthropic directly'), explains that _apiKey is passed straight through to api.anthropic.com, and previews the return structure. 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?

Three sentences, front-loaded with the core function, then default/cost, then output and use cases. Every sentence adds unique 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?

With no output schema, the description compensates by specifying the per-model return fields and the combined view. It also covers the key parameter behavior and use cases. The annotations already cover safety, so the context is complete for an agent to invoke 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 is 3. The description adds meaning to 'models' by stating the default (Workers AI Llama-3.3-70b free) and the condition for using Anthropic, and clarifies the _apiKey's role and cost. This 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 a specific verb 'probe' and names the resource (LLMs) plus the output (visibility score 0-100). It clearly states the tool's function. However, it does not explicitly differentiate itself from the sibling 'scan_competitor_ai_presence', which could be a near-alternative, so it misses the top score.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also tells when to pass _apiKey (to also probe Anthropic) and notes cost implications. However, it does not name alternative sibling tools or state when NOT to use this tool, so not 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is clear. The description adds significant behavioral context: it routes to the right tool among 5,462 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a fast single call. It also clarifies behavior for breaking news. No contradiction with annotations.

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

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

The description is front-loaded with the key guidance ('PREFER OVER WEB SEARCH') and is dense with useful information. However, it is somewhat lengthy, listing many domain examples and multiple usage triggers, which could be trimmed without losing value. Still, every section serves a purpose and the structure is logical, making it more than adequate.

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 as a meta-router, the description covers all necessary aspects: what it does, when to use it, alternatives, behavior (routing, citation URIs, performance), and coverage breadth. With no output schema, the mention of 'returns the structured answer with stable pipeworx:// citation URIs' adequately sets expectations. 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?

The schema covers all 6 parameters with descriptions stating they are aliases for 'question', resulting in 100% schema description coverage. The description itself does not add additional parameter semantics beyond the schema, but since schema coverage is high, baseline 3 is appropriate. The description's examples illustrate valid inputs but add no new meaning beyond the schema's definition.

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 ask_pipeworx does: it answers questions by routing to the appropriate tool among 5,462 sources and returns structured, cited answers. It distinguishes itself from siblings by positioning as the default entry point and explicitly contrasting with ask_pipeworx_grounded and deep_research. The verb+resource is specific and the scope is well-defined.

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 guidance is explicit and thorough. It says to prefer over web search for a wide range of factual domains, triggers on user phrasing like 'what is', 'look up', 'get the latest', and gives concrete examples. It also provides clear alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions. This fully satisfies the when, when-not, and alternatives criteria.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. Beyond that, the description adds valuable context: the tool is a live beta, may have routing improvements under test, currently matches ask_pipeworx exactly, and results feed into merge decisions. This exceeds the annotation baseline.

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

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

Three sentences, each necessary: definition, current state, usage/behavior. No fluff, logically ordered, and efficient for the tool's complexity.

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

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

The description covers the tool's nature, current state, usage condition, and relationship to ask_pipeworx. Since there's no output schema, it references 'same response shape' which relies on sibling knowledge, but this is sufficient given the tool's context.

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

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

Schema coverage is 100% with a detailed description of the 'question' property and aliases. The tool description adds no parameter-specific information, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape. It explicitly distinguishes from siblings ask_pipeworx and ask_pipeworx_grounded by framing it as the experimental edge with candidate routing improvements.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear when-to-use condition. It also notes comparisons against the stable router and that it is a full working router, but does not explicitly state when not to use it or mention alternative tools beyond ask_pipeworx.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behaviors: it routes like ask_pipeworx, fills arguments, fetches data, extracts only from tool results, returns a structured response with refusal reasons, and costs an extra LLM call. This adds substantial context 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?

Three dense sentences: first defines the core purpose, second details the return/refusal format, third covers use cases and tradeoff. Every sentence earns its place, front-loading the most critical information.

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

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

The tool is complex with no output schema, but the description fully covers behavior, return structure, refusal reasons, and comparison to sibling tools. It even specifies the extra LLM call cost, making it complete for an agent to decide and invoke 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% with all six parameters documented as aliases for 'question,' so the schema already fully explains the parameters. The description does not add parameter-specific meaning, but it doesn't need to; 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 this is a 'hallucination-resistant answer mode' that extracts answers only from tool results, distinguishing it from the sibling ask_pipeworx. It specifies the verb (answer) and resource (grounded mode), with explicit differentiation via the grounded/evidence-based approach.

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

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

Provides explicit when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives a cost-based exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' clearly naming the alternative.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses rich behavioral detail: fan-out to parallel data packs, resolver contract with confidence levels, parent_event extractor, news fallback with _fallback_attempted fields, safety short-circuits for low-confidence matches, and handling of closed/dead markets. It even explains resolution-rule risk (e.g., refund_50_50) and how that affects betting decisions. This is far beyond annotation disclosure.

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 long, the description is meticulously structured with uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and every sentence carries unique information. It is front-loaded with the core purpose, then systematically covers edge cases without redundancy. The length is justified by the tool's complexity.

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

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

With no output schema, the description takes on full responsibility for explaining return values. It covers result.market, result.analysis, result.evidence, market_match_confidence, parent_event, news fields, safety statuses (low_confidence_match, market_closed_or_inactive), and tradeability warnings. Also includes concrete fan-out examples for different bet categories, making it highly complete for an AI agent.

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

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

The input schema already covers all three parameters with descriptions, so the baseline is 3. The description adds meaningful semantics: 'quick = 2-3 evidence sources' for depth, and the include_raw explanation about response size (~20KB vs 50KB-500KB) and when to pass true. It also gives concrete examples of market slug and URL formats, enhancing 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call,' a specific verb+resource statement that distinguishes this tool from siblings like polymarket_arbitrage or polymarket_edges. It also clarifies the input formats (slug, URL, question text), making the tool's scope unmistakable.

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

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

The description explicitly states 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving concrete usage contexts. It does not explicitly mention when to use alternatives (e.g., polymarket_arbitrage), but provides extensive behavioral warnings about blocking and low-confidence matches, which serve as usage guardrails.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: it resolves drug names to all matching molecule forms (including salts and branded formulations), searches all of them simultaneously, and lists each molecule ID searched so empty results are interpretable. It also details the return fields and cites the data source (ChEMBL, EMBL-EBI). This goes well beyond the annotations and provides a clear picture of the tool's side-effect-free behavior.

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

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

The description is detailed but every sentence carries weight: it starts with the core purpose, then gives query examples, explains the resolution behavior, lists return fields, and ends with clear usage guidance. It is well-structured, front-loaded, and avoids redundancy. The length is justified by the tool's complexity.

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

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

Even without an output schema, the description explicitly enumerates the returned data: action_type, mechanism_of_action, molecular target with ID and organism, molecule form, max clinical phase, curator comments, and PubMed references. It also covers how name resolution works and how to interpret results. This is complete context for an agent to predict the tool's output 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 coverage is 100%, and each parameter has an explanatory description; the description does not need to repeat them. It does add context about the resolution strategy (e.g., why the 'candidates' parameter matters) and the meaning of action_type, but this is marginal. Per the baseline for high schema coverage, a 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 opens with a specific verb+resource: 'Mechanism of action of a drug, from its NAME (or a ChEMBL molecule ID).' It includes concrete query examples like 'how does metformin work' and 'what does X inhibit,' making the tool's purpose unmistakable. This clearly distinguishes it from sibling tools like 'molecule' or 'target' by focusing on mechanism-of-action queries.

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

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

The description provides clear usage context: 'Reach for this for pharmacology, mode of action, drug-target identification, and any "how does this drug work" question.' It does not explicitly name alternatives or state when not to use the tool, but the context is strong enough to guide an agent. No exclusionary guidance is provided, so it falls short of 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 (readOnly, idempotent), the description reveals specific behaviors: data sources (SEC EDGAR/XBRL, FAERS/FDA), correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. This is substantial contextual transparency.

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

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

The description is dense and front-loaded with natural-language triggers, then purpose, then guidance, then data details. It is slightly long but every sentence adds value and follows a logical structure, making it more informative than verbose.

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

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

With no output schema, the description compensates by stating return format (paired data + pipeworx:// citation URIs), sorting behavior, and data source specifics. It covers both entity types and edge cases like fiscal year handling, making it complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters, but the description adds deeper semantics: it explains what each type retrieves and provides concrete examples of valid values (tickers vs drug names), enriching the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It uses specific verbs and examples ('compare', 'rank', 'which is bigger') and differentiates from sequential lookups, distinguishing it from sibling tools like entity_profile or search.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and 'Replaces 8–15 sequential lookups.' It also clarifies when to use type='company' vs type='drug', giving clear conditional usage.

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

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

The description extensively discloses behavior beyond annotations: account requirements, free vs paid tiers, parallel decomposition across 5,462 tools, gaps[] never invented, citation_uri fetchability guarantee, semantic excerpting, hop field, contradictions[] for standard/thorough, and expected latency ranges. Annotations already indicate read-only/idempotent/open-world, and the description adds rich context without contradicting them.

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

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

The description is dense but well-structured, front-loading the most critical actionable info (account required, sign-in link, alternative if not signed in). It uses parentheticals and semicolons to pack multiple details efficiently. It is long (over 200 words), but every clause earns its place given the tool's complexity; still, a few details (e.g., specific tool count '5,462') could be trimmed without losing meaning.

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

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

With 2 params, no output schema, and rich annotations, the description carries the full burden of explaining a complex tool. It covers prerequisites (account, paid plan), expected output structure (findings packet, gaps[], contradictions[], hop field, citation_uri), failure modes (empty gaps for non-structured topics), performance expectations (15-90s), and comparison to siblings. This is complete enough for an agent to select and use the tool correctly without further clarification.

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 meaningful context to the `depth` parameter by explaining the behavioral difference between quick/standard/thorough (single hop vs gap recovery vs iterative leads), which goes beyond the schema's terse enum descriptions. It also clarifies that broad/multi-part questions are acceptable for the `question` param, reinforcing the schema's note that decomposition is the point.

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 grounded multi-source research across Pipeworx's structured data sources in one call, with a specific verb ('research'), resource ('1419 STRUCTURED data sources'), and scope ('broad/multi-part questions'). It explicitly distinguishes from siblings by saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and live news.

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?

This is exemplary usage guidance. It explicitly says when to use this tool (broad/multi-part questions over structured data), when NOT to use it (breaking/colloquial current news), and names the alternative (ask_pipeworx) with reasons. It also explains depth tiers and second-hop iteration behavior.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This reveals the tool's output behavior and efficiency. 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 sentences, front-loaded with purpose and usage, followed by return behavior and a practical recommendation. Every sentence carries weight—no fluff or repetition. Excellent structure for quick agent comprehension.

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

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

Despite lacking an output schema, the description fully explains what is returned (names, descriptions, schemas, examples) and why to call it first. It covers purpose, usage, and result format. Minor omissions like edge-case behavior or parameter alias handling are already covered in the schema, so the description is sufficient for a discovery tool.

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

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

Schema description coverage is 100%, with each parameter clearly documented including aliases. The description adds a brief note about 'top-N' and the limit parameter's effect, but mostly reiterates schema info. Since the schema covers everything, the description doesn't significantly add parameter meaning beyond what's already present.

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 uses specific verb 'Find' and resource 'tools', and enumerates covered domains (SEC filings, financials, FDA drugs, etc.), clearly distinguishing it as a discovery meta-tool. It also explicitly frames itself as the first call to see the option set, differentiating from sibling search and analysis 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?

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for:' and gives concrete contexts. Also provides a clear directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly guides selection among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds some behavioral context by specifying 'approved' indications and 'max clinical trial phase', but it doesn't disclose additional traits like authentication needs or rate limits. This is acceptable but not rich.

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

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

The description is a single, well-structured sentence that front-loads the main purpose and lists key return fields without unnecessary wording. Every part adds value.

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

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

With an output schema present, the description does not need to explain return values in depth. It covers the main filters and return fields, but misses the limit parameter and does not mention open-world behavior beyond annotations. Overall, it is complete enough for a read-only query tool.

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

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

Schema descriptions are 0% covered. The description explains molecule_chembl_id and mesh_id ('MeSH disease ID'), which is helpful, but it omits the 'limit' parameter entirely. Since description must compensate for lack of schema descriptions, partial coverage earns a mid-range 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 a specific action ('Retrieve approved drug indication records from ChEMBL'), identifies the resource, and specifies filters and return fields. This distinguishes it from sibling tools like molecule or target, which focus on other entities.

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

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

The description provides clear context on when to use the tool (when needing drug indication data filtered by molecule or MeSH ID) and what it returns. However, it does not explicitly name alternatives or exclusions, so it stops short of a perfect 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?

The description adds substantial behavior beyond the readOnly/idempotent annotations: it discloses fan-out across multiple APIs, return field specifics, the USPTO PatentsView API sunset with soft-fail behavior, and the GDELT→GNews fallback. This is rich, honest behavioral disclosure.

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

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

The description is a single dense paragraph that packs a lot of necessary detail. It is front-loaded with examples and organized by semicolons, but it is longer than strictly necessary. Every sentence earns its place, though a bulleted return structure would slightly improve scannability.

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

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

With no output schema, the description fully enumerates the return payload (cik, filings, fundamentals, patents, news, LEI) and clarifies edge behaviors like patent soft-fail and name rejection. For the tool's complexity, this is complete and self-contained.

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

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

Schema coverage is 100%, and both schema descriptions already explain the parameters (ticker/CIK, no names). The description repeats this almost verbatim without adding new semantic meaning. It offers example queries, but those are about purpose, not parameter semantics. Baseline 3 is appropriate.

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

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

The description opens with concrete example queries like 'Tell me about X' and 'research Acme', then states a specific verb+resource: 'full cross-source profile of a US public company'. It distinguishes itself from siblings by explicitly saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and by referencing resolve_entity for name-only inputs.

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 provides explicit when-to-use context ('when the user asks for a holistic view'), a clear when-not ('names not supported'), and names the alternative tool (resolve_entity). This meets the highest bar for 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 destructiveHint=true and idempotentHint=true. The description adds context ('previously stored memory') and usage scenarios, but does not disclose additional behavioral traits such as permanence or error handling. Consistent 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, front-loaded with the action, then usage context, then related tools. Every sentence provides value with no redundancy.

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

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

This is a simple one-parameter tool with no output schema and full annotations. The description covers purpose, when to use, and relationship to siblings, which is complete for this complexity.

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

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

Schema coverage is 100% and the 'key' property is clearly described as 'Memory key to delete'. The description's 'by key' adds no new meaning beyond the schema, so a 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 'Delete a previously stored memory by key' – a specific verb and resource. It also differentiates from siblings by mentioning 'Pair with remember and recall', helping the agent understand its place among related 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?

Provides explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It does not include when-not-to-use or alternative names, so it falls short of 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?

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds process detail: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations by explaining the internal workflow, though it doesn't mention failure modes or network dependency specifics.

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: the first states the core action, the second explains the process, and the third lists use cases. Every sentence is informative with no wasted wording.

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

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

For a simple 2-param read-only tool with annotations, the description covers the output format ('single text blob ready to drop at site-root/llms.txt'), process, and use cases. Even without an output schema, it clearly communicates what the tool returns.

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 'url' and 'max_links' described. The description does not add parameter-specific details beyond the schema, so the baseline 3 applies.

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

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

The description uses specific verbs ('Generate', 'Fetches', 'extracts', 'emits') and clearly identifies the resource (llms.txt file) and its purpose for AI crawlers. It distinguishes from sibling tools by targeting llms.txt generation specifically.

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 use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving clear context on when to use the tool. It doesn't mention alternatives or exclusions, but the guidance 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful context by specifying the scope ('caller's active subscriptions') and the returned fields, which informs the agent about what to expect without over-explaining.

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: the first delivers the core purpose, the second lists return fields and practical use cases. Every sentence earns its place, and there is no wasted text or repetition of schema 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?

For a simple list tool with one optional parameter and no output schema, the description is sufficiently complete. It explains what is returned, the scope (active subscriptions), and why an agent would call it, making it self-contained for correct usage.

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

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

Schema coverage is 100% and the single parameter include_inactive is already well described in the schema. The description does not add parameter-level detail but does list return fields, providing some value beyond the schema.

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

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

The description clearly states a specific action ('List the caller's active subscriptions') and identifies the resource. It also distinguishes itself from sibling tools like subscribe and unsubscribe by framing the purpose as reviewing existing monitoring before adding more or finding an id to cancel.

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 use cases: review what you're monitoring before adding more, or find an id to cancel. It does not explicitly state when not to use it or name alternative tools, but the context is clear enough for an agent to decide.

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

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

The description adds behavioral context beyond the annotations: 'returned verbatim from the API' and 'unshaped rows' disclose that no transformations are applied. Annotations already cover read-only and idempotent hints, so the extra context is a bonus, though it doesn't detail edge cases like missing IDs.

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

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

Two concise sentences front-load the core purpose and reference the sibling tool. Every clause earns its place with no redundancy or filler.

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

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

For a single-parameter read-only tool with a clear output schema and strong annotations, the description covers all essential context: the exact input, output nature, and usage conditions. Nothing critical is missing.

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

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

The schema provides a minimal description ('molecule_chembl_id'), but the tool description enriches it by specifying 'exact molecule ChEMBL ID' and giving an example format. This clarifies that partial or fuzzy IDs are not acceptable, adding meaningful semantic 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 clearly states the tool returns raw ChEMBL mechanism records for a single exact molecule ChEMBL ID, using a specific verb ('returned') and resource. It distinguishes itself from the sibling tool chembl_mechanism by framing its scope (already have the ID) and output (unshaped rows).

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

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

Explicitly states when to use this tool ('when you already hold the precise molecule ID and want the unshaped rows') and identifies an alternative, chembl_mechanism, for starting from a drug name. This is textbook 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 declare read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral context beyond the example, but there is no contradiction. It is adequate given 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 a single concise sentence that front-loads the primary purpose and includes an illustrative example without unnecessary words.

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

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

For a simple one-parameter lookup with an output schema present, the description provides all necessary information: what the tool does, the input format, and an example. No returned-value explanation is needed given the 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 has 0% property description coverage, but the description explicitly explains the chembl_id parameter and provides a helpful real-world example (CHEMBL25 = aspirin), adding meaning beyond the schema's bare type and example.

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

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

The description clearly identifies the tool as retrieving the full molecule record for a given ChEMBL ID, with a concrete example linking CHEMBL25 to aspirin. This distinguishes it from sibling tools that focus on specific aspects like mechanism or target.

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

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

The description implies the tool is for full molecule lookups but does not explicitly state when to use it over alternatives such as mechanism or target. The example provides context but no exclusions or alternative 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?

Despite annotations being all false, the description discloses substantial behavioral context: rate-limiting ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and lifecycle behavior ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'). This goes far beyond structured fields.

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 one dense paragraph, but every sentence adds critical operational information: when to use, exclusions, token mechanics, rate limits, and roadmap impact. It is longer than typical but justified by the tool's complexity and follow-up flow. Slightly front-loaded with the main purpose before diving into caveats.

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 still explains both immediate output (claim_token) and later retrieval semantics. It covers all usage scenarios, boundary conditions, and operational constraints. For a feedback tool with nested context and an unusual claim-token mechanism, this is thorough and complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token workflow (returned token, later invocation pattern) and clarifying that the message should reference Pipeworx tools rather than end-user prompts. It does not repeat schema definitions but enriches them.

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

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

The description uses a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback channel from siblings like ask_pipeworx by framing it as a reporting mechanism for Pipeworx tools, not a general Q&A tool.

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

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

The description gives explicit when-to-use criteria: bug, feature/data_gap, praise, and 'other.' It also states a clear when-not-to-use: do not report issues for tools from other MCP servers, and instead 'file it with that server instead.' It further instructs on how to phrase feedback ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context: it states the data is 'self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and reveals cache timing ('Cached 5min-1h depending on window'). This 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?

The description is compact and well-structured: one sentence for the core output, and a second sentence with numbered use cases. The additional data-source/caching note is a single clause, adding value without bloat.

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-parameter read-only tool, the description is thorough: it covers what it returns (top tools, top packs, volume), why it's useful, data provenance, PII handling, and caching. The absence of an output schema is mitigated by the explicit (pack, tool, count) shape.

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

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

Schema coverage is 100% for the single 'window' parameter, with enum values and descriptions already provided. The description mentions the windows ('24h, 7d, or 30d') but does not add significant semantic detail beyond the schema's own description of short vs. long window tradeoffs.

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 'What other AI agents are calling on Pipeworx right now' and explicitly lists outputs: 'top tools, top packs, and total call volume'. This clearly distinguishes it from sibling analysis tools like ask_pipeworx or discover_tools by focusing on aggregate agent behavior.

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

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

The description provides three explicit use cases: discovering hot data sources for current events, confirming canonical tools before asking, and checking alignment with other agents' needs. While it doesn't list exclusions or alternative tools, the use-case list gives clear contextual 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial context beyond that: the semantic anchor threshold (Jaccard ≥0.30), placeholder filtering rules, the fill check distinguishing theoretical vs realizable edge, and the warning not to trade when realizable_edge_pp ≤ 0. No contradictions with annotations.

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

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

The description is long but densely informational, with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded no-args usage. Every sentence serves a purpose given the tool's complexity, though a slightly tighter presentation could be achieved. It earns its length.

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

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

With no output schema present, the description adequately details response structures ('opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)', 'partition_check{...}') and handles edge cases like placeholder fractions, low similarity, and fill-check interpretation. It is complete enough 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?

The input schema covers 100% of parameters with descriptions, but the tool description enriches each parameter with real-world semantics: it provides example event slugs ('fed-decision-may-2026'), notes that full URLs are accepted, gives topic seed examples, and explains which mode each parameter activates. This goes well beyond the schema's bare property descriptions.

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

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

The description opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', clearly stating the verb, resource, and method. It distinguishes itself from siblings like polymarket_edges by specifying the arbitrage detection approach and explicitly describing three modes (trending_scan, event, topic).

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

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

The description gives explicit when-to-use guidance: 'Call with NO args for a trending_scan...; pass event for...; topic for...'. It also names an alternative tool: 'For custom sizing use polymarket_fill_risk', and recommends modes per use case. This clearly differentiates usage across scenarios.

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

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

The description goes far beyond the annotations (readOnly, idempotent, non-destructive) by disclosing caching behavior ('Cached 1h at the KV level'), internal model calculations (e.g., GDELT ratios, per-sport α values, Kelly caps), and the 24h-move warning. It also explains why Fed signals are unreliable, which is genuine behavioral context. No contradictions with annotations.

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

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

The description is very long and dense—it packs model formulas, per-sport alphas, and detailed response structure into a single block of text. It does have clear internal headings (e.g., 'TRADEABLE-EDGE KNOBS', 'RESPONSE TOP-LEVEL') that aid navigation, and the complexity of the tool justifies some length. Still, several details (e.g., exact alpha values, Run 8 gates) are likely non-essential for an LLM to invoke it correctly.

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

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

For a complex tool with 9 parameters and no output schema, the description covers the response top-level structure (by_segment, fed_candidates, diagnostics), explains why segments might be empty (filter_skips), and describes the return fields (edge_pp_net, kelly_fraction). It also notes the 1h cache and keying on knobs, leaving little ambiguity about what the agent will receive.

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 schema coverage is 100% and each parameter has its own description, the tool description adds substantial cross-parameter semantics: explains 'TRADEABLE-EDGE KNOBS' and how min_partition_leg_kelly specifically applies to basket trades, why default slippage is 0.3pp (fee-free but thin depth), and how min_edge_pp is evaluated net of slippage. This enriches the schema beyond simple field descriptions.

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

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

Description starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' — a specific verb and resource, and clearly explains the user question it solves ('what should I bet on today'). It differentiates from siblings like polymarket_arbitrage and polymarket_edge_tracker by its segmentation and data source, so it's unambiguous.

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

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

Provides clear context for when to use: 'Built for ... agents discover opportunities without paging hundreds of markets.' It also describes knob-based filtering and diagnostics, implying usage for opportunity discovery. However, it doesn't explicitly name alternatives or state when not to use this tool, though the sibling set and unique output make the intended context clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes well beyond by explaining snapshot TTL limits, cache-miss writing behavior, decay computed from daily closes not intraday, and the meaning of date gaps. It also uses 'LIMITS' to disclose boundaries, which adds rich behavioral context 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 well-structured with clearly segmented parts: purpose, args, response, and limits. It is dense but every sentence earns its place—no filler or repetition. The front-loaded purpose sentence immediately conveys the tool's unique value.

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

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

With no output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) including field-level semantics and the meaning of trend values. It also covers limitations (snapshot TTL, start date, daily closes), making the tool's behavior fully understandable for an agent to select and invoke it.

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 (days and window) are already described in the input schema, so the baseline is 3. The description adds meaningful context by explaining that 'days' is a lookback across snapshot history, not just calendar days, and that 'window' selects a snapshot family. It also clarifies how these parameters affect the response structure (e.g., tracking across prior snapshots).

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 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' which clearly identifies the tool's specific function and scope. It distinguishes itself from sibling tools by focusing on historical persistence and decay rather than current edge values, answering 'how long has this edge existed and is it shrinking?' This is a specific verb+resource+scope definition.

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 context for when to use the tool: when you need to understand edge persistence and decay over time, especially the distinction between fresh and old edges. It implies the use case but does not explicitly name alternative tools or state exclusions (e.g., 'for current edges use polymarket_edges'), so it lacks explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds extensive behavioral details beyond that: single-market vs basket mode behavior, specific output fields (top_of_book, vwap_fill_price, slippage_pp, verdict), and the risk warning about partial fills converting arbitrage into unhedged directional positions. 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 (~250 words) but front-loaded with the core purpose and uses clear uppercase section markers (SINGLE-MARKET, BASKET) to separate modes. Every sentence contributes necessary information for correct invocation, though a bulleted structure would improve scannability, preventing a 5.

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 enumerates return values for both modes: single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg details, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers prerequisites and the risk context, making it complete for a complex read-only 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 baseline is 3. The description enriches parameter understanding beyond the schema: for size_usd it clarifies 'max spend on buys, target proceeds on sells' and in basket mode 'settlement notional—shares per leg,' and for side it explains the default auto behavior based on partition sum. This added interpretation 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 description opens with a precise verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by focusing on fill risk rather than signal generation, and explicitly relates to polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit when-to-use: 'USE THIS before acting on any polymarket_arbitrage... signal or any polymarket_edges trade above ~$500,' with a strong rationale about thin books and partial fills. However, it does not include explicit when-not-to-use conditions or directly name alternative tools to use instead, so it falls short of 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?

Annotations state readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral detail beyond this: it explains the two modes, response structure (leg-by-leg prices, spread), safety fields (compatibility_warning, temporal_alignment, skipped counters), and what each condition means. It also discloses limitations like 'pre-mapped ≠ tradeable.' No contradictions with annotations.

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

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

The description is long but densely packed with unique information. It is front-loaded with the core purpose and then systematically covers modes, response fields, safety fields, and caveats. Some sections (e.g., the long explanation of compatibility_warning cases) are verbose but justified for the tool's complexity. It could be tightened, but no sentence is pure 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?

Given the tool's complexity, absence of an output schema, and rich annotations, the description is exceptionally complete. It explains not only the return values (leg venue prices, spread) but also edge cases (temporal alignment, skipped cross types, unmatched pairs) and their significance. This is sufficient for an agent to invoke the tool and interpret responses 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 parameters are documented, but the description adds major semantic value: it explains that topic is a shortcut (listing all 10 options), that explicit tickers/slugs override the topic-mapped side, and what each mode does. It also gives examples of ticker formats. This goes far beyond the schema descriptions.

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

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

The description starts with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison, and explicitly describes two modes (topic and explicit). This leaves no ambiguity about what the tool does.

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

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

The description provides clear context on when to use each mode: topic shortcuts for pre-mapped events and explicit tickers/slugs for custom pairings. It also notes that most pre-mapped topics are not tradeable, guiding expectations. However, it does not explicitly name alternatives or provide exclusion criteria for sibling tools, so it stops short of a full when-to-use/not-use guide.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful context: scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of retrieving vs listing keys. It does not contradict annotations.

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

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

Three sentences. The first sentence carries the core mechanism, the second gives use cases, the third covers scoping and companion tools. 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 one-optional-parameter read-only tool, the description covers behavior (retrieve/list), scope, and relationship to siblings, with strong annotation support. No output schema is needed since return behavior is implied.

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 of the key parameter. The description reinforces this with examples of key values ('user's target ticker, an address, prior research notes') and the omit-to-list behavior, adding semantic nuance beyond the bare schema.

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

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

The description opens with a specific verb-resource pair: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly identifies the tool's function and distinguishes it from siblings by referencing 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?

It explicitly states when to use: 'Use to look up context the agent stored earlier' with concrete examples, and names alternatives: 'Pair with remember to save, forget to delete.' This gives clear usage context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: each alert carries source, citation_uri, and raw payload; mark_read:true affects future calls; and polling is acceptable. This exceeds the baseline set by annotations, though it doesn't cover auth or rate limits.

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

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

Three sentences, front-loaded with the primary purpose, and every sentence adds information. No filler or repetition of schema details already present.

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?

Without an output schema, the description still explains the return payload contents (source, citation_uri, raw event payload) and key behaviors like mark_read and polling suitability. It's complete for a straightforward read tool, though it could mention pagination or the default limit.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond by giving a concrete example for 'type' ("sec_8k"), clarifying 'since' as ISO timestamp, and explaining the behavioral effect of mark_read. It adds meaningful value without being redundant.

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 starts with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly identifies what the tool does and distinguishes it from siblings like recent_changes and list_subscriptions by focusing on the evaluator's persisted 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?

It provides clear usage context: polling is fine, and an alternative HTTP endpoint (registry.pipeworx.io/alerts.json) is mentioned for scripts/dashboards. However, it does not explicitly state when this tool should be preferred over sibling tools or give exclusions, so it misses the top score.

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

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

Goes beyond annotations by describing fan-out behavior, GDELT→GNews fallback logic, and USPTO soft-fail due to PatentsView sunset. Also discloses return structure (changes[], total_changes, 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?

Dense but efficient: starts with concrete user intents, defines the tool, lists sources, explains `since`, then describes output and alternative. Every sentence contributes unique 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?

Given the multi-source complexity, the description covers all essential aspects: what sources are queried, fallback/soft-fail behavior, the return format, and when to use a different tool. No output schema exists, so this description fully compensates.

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 baseline. The description adds value by explaining `since` formats (ISO vs relative) and recommending '30d' or '1m' for typical monitoring. It also confirms `value` can be ticker or CIK 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 clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from sibling entity_profile by explicitly naming when to use that alternative.

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

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

Provides explicit when-to-use context: 'What's new with X' / 'latest on Y' and notes it does this in ONE parallel call. It also gives an explicit exclusion: 'Use entity_profile instead when you want the static profile... regardless of window.'

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 (idempotentHint, readOnlyHint, destructiveHint), the description discloses important behavioral traits: the memory is scoped by identifier, authenticated users get persistent memory, and anonymous sessions retain memory for only 24 hours. It does not explicitly mention what happens on overwriting an existing key, but the idempotent hint covers some of that context.

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

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

The description is compact and well-structured: it opens with the core action, gives use-case examples, then explains scoping and retention, and ends with companion tools. Every sentence earns its place without unnecessary repetition 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?

For a simple two-parameter save operation with no output schema, the description covers the essential operational context: what to save, when to use it, how long it persists, and how it relates to recall/forget. It does not describe return values or error behavior, but those are not critical for invoking this tool effectively.

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

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

The input schema already describes both parameters (key and value) with 100% coverage, including examples for keys and the note that value can be any text. The description adds minimal extra parameter meaning, so it stays at the baseline for high schema coverage.

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

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

The description clearly states a specific verb and object: 'Save data the agent will need to reuse later.' It also identifies this as a key-value memory store and differentiates it from sibling tools by explicitly referencing recall and forget, making its purpose unmistakable.

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

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

It provides explicit usage guidance with concrete examples: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It also explains the pairing with recall and forget, which serves as an alternative/companion tool reference.

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, open-world, non-destructive behavior. The description adds valuable behavioral context beyond annotations: internal cascading lookups, auto-disambiguation, and the exact outputs (ticker, CIK, company_name, RxCUI, ingredient, brand) including citation URIs. This is rich and helpful for understanding cost and result format.

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

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

The description is moderately long but every sentence earns its place: example queries, core purpose, usage directive, supported types with outputs. It is well-structured and front-loaded with the most important information, then followed by details. 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 there is no output schema, the description carries the full burden of explaining what the tool returns. It lists all relevant result fields and citation URIs, covers both entity types, and provides usage context. It is complete enough for an agent to correctly select and invoke the tool without ambiguity.

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, so baseline is 3. The description adds meaningful extra context: it explains what each supported type returns, that company accepts ticker/CIK/name (auto-disambiguated), and that drug accepts brand or generic. It goes beyond the schema descriptions by giving examples and output implications.

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 immediately states a specific action (resolve a user-spoken name to canonical identifier) with concrete examples ('What's the ticker for…'). It clearly distinguishes from siblings by noting the identifiers are 'other tools require as input,' and separates supported types (company, drug) with return values.

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

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

Provides explicit when-to-use: 'Use FIRST whenever you have a name but need an ID.' This is a strong directive that orients the agent. However, it does not mention explicit when-not-to-use scenarios or name alternative tools (e.g., entity_profile), so it falls short of the 5 criterion.

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

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

Annotations already cover read-only and idempotent behavior. The description adds valuable behavioral context by stating it probes each entity with ai_visibility_check, ranks results by score, and returns specific metrics (score, confidence, signal density). This goes beyond the structured data and gives insight into how the tool operates and what it returns.

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, front-loaded with the main purpose, and each sentence provides distinct value: what, how/when, and output. There is no filler or redundancy.

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

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

The description covers purpose, usage, mechanism, and output (ranked list with score, confidence, signal density). Given the tool has no output schema, mentioning the output fields is helpful. The schema covers parameters, and annotations cover safety. It could be more complete by mentioning that multiple calls to ai_visibility_check are made (potential latency/cost), but that is not critical.

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 all parameters are already well-documented. The description adds minimal parameter semantics beyond reinforcing the entities parameter ('your brand + N competitors') but does not introduce new information about models, _apiKey, or context. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states a specific action: 'Compare AI visibility across multiple entities side-by-side.' It further specifies the mechanism ('Probes each entity... with ai_visibility_check'), the output ('Returns ranked list with score, confidence, signal density per entity'), and distinguishes itself from the sibling tool ai_visibility_check by being the multi-entity comparison version.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' with an example query. It implies when to use this tool (when comparing multiple entities) versus the single-entity alternative (ai_visibility_check). However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already establish a safe read-only scan, but the description adds critical behavioral context: it is a composite call that fans out to multiple services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed reports timeouts. This rich transparency is exactly what an agent needs to manage timeouts and partial results.

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

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

The description is dense but efficient, packing purpose, usage, output shape, ecosystem scope, performance caveat, and error handling into a compact paragraph. Every sentence adds unique, actionable information; there is no fluff. It front-loads the core purpose and gets to usage guidance immediately.

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 (multi-source composite, external APIs, no output schema), the description is exemplary. It explicitly lists the summary fields, per-advisory details, links, and alternative versions — fully covering return values without an output schema. It also explains ecosystem limitations, timeout behavior, and partial-failure semantics, making it complete for an agent to judge outcome and formulate fallbacks.

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

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

Schema coverage is 100% — both 'package' and 'version' have detailed descriptions covering scoped packages, examples, and default behavior. The description does not add new parameter-level semantics beyond the schema; it merely repeats the default-to-latest and scoped-package idea in its output block. Per policy, high schema coverage yields a baseline of 3, and the description doesn't elevate it.

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

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

The description opens with a clear, specific verb+resource: "Composite 'should I add this npm package to my project' check in ONE call — fans out across deps.dev ... and bundlephobia." It explicitly names the external services and the exact decision it supports, distinguishing it from sibling tools like scan_competitor_ai_presence. The NPM-only scope in v1 further sharpens 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?

"Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'" provides explicit trigger scenarios. It also gives an explicit exclusion: "PyPI / Maven / Cargo / Go fall under deps.dev:version directly," telling the agent when not to use this tool. This goes beyond typical one-line usage advice.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond annotations by explaining that results are ChEMBL IDs and summary fields meant for chaining into other tools, which helps the agent understand the output's role in workflows.

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 zero wasted words. The first sentence delivers the core function and output format; the second sentence offers a relevant alternative. It is front-loaded with the most important information.

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

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

The tool has rich annotations (read-only, idempotent) and an output schema, reducing the description's burden. The description covers the search scope, result format, and downstream usage, making it sufficiently complete 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 has 100% coverage with descriptions for type, limit, and query, so parameters are already well-documented. The description adds no significant meaning beyond what the schema provides, 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 it performs full-text search of the ChEMBL database for molecules, targets, assays, or documents, and returns ChEMBL IDs and summary fields. It distinguishes itself from chembl_mechanism by noting that tool takes a drug name directly for mechanism, making the purpose specific and well-scoped.

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 mentions pairing with chembl_mechanism as an alternative for direct drug name queries, providing clear usage context. It also implies a workflow by stating results can be passed to molecule, target, or activities. However, it does not explicitly rule out other search-related siblings like search_within.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses internal behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flag. It also explains return values (passages with offsets and similarity scores). No contradiction with annotations.

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

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

The description is longer than average but every sentence earns its place: main purpose, examples, use case, pairing, algorithm, and limitation. It is front-loaded with the core verb and resource, and while slightly dense, it avoids 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 has no output schema, the description provides a full picture: return format, algorithmic details, input limits, and integration guidance with a sibling tool. This is sufficient for the agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates parameter meaning (e.g., 'text you already pulled') and gives example queries, but does not add substantial new semantics beyond the schema's own descriptions.

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

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

The description opens with 'Semantic search INSIDE a fetched record', providing a specific verb and resource. It clearly distinguishes from siblings like search (which likely searches external sources) and ask_pipeworx_grounded (which grounds over passages), making the tool's role unambiguous.

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

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

Explicitly states when to use it: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, offering a clear alternative workflow. This gives the agent concrete context for tool 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 substantially enriches the annotation hints. It discloses the OAuth requirement, the 10/day SMS cap, phone verification prerequisites, webhook auto-disable after 10 consecutive failures, and that the webhook signing secret is returned only once. These are behavioral traits not present in the annotations and are critical for safe invocation.

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

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

The description is dense but efficiently organized: purpose first, then prerequisites, then supported types, then delivery channels. Every sentence adds distinct value (e.g., caps, verification steps, webhook signing details) without repetition or filler. It is appropriately sized for a complex tool with nested parameters.

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 (3 parameters, nested objects, 5 subscription types, multiple delivery channels) and lack of an output schema, the description is remarkably complete. It explains return value (subscription id), authentication needs, per-type params, delivery behavior, and failure semantics. No obvious gap remains for an agent to invoke it correctly.

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

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

The input schema already covers all parameters with descriptions (100% coverage), but the description adds meaning via concrete examples for each subscription type, delivery channel specifics, and constraints like E.164 phone format and webhook HTTPS-only. This goes beyond the schema's surface-level definitions, though the schema already carries much of the semantic weight.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on the creation act, and enumerates concrete subscription types and delivery channels that make its scope unmistakable.

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

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

The description gives clear context for when to use the tool: it requires a Pipeworx OAuth account, explains that anonymous/BYO cannot persist subscriptions, and provides type-specific examples. It does not explicitly name alternatives (e.g., 'use recent_alerts for pulling'), but it instructs users to pull the feed via recent_alerts or the registry URL, implying a monitoring creation role.

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 and non-destructive behavior, but the description adds valuable transparency about the output structure (category-bucketed example questions with tool+argument shapes) and how the tool behaves differently depending on whether a topic is passed. This goes well beyond the annotations.

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

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

The description is somewhat long but well-structured and front-loaded with typical user queries. Each section—purpose, output, usage—earns its place, and there is minimal redundancy, though it could be marginally tightened.

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

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

For a tool with a single optional parameter and no output schema, the description is remarkably complete. It covers purpose, output, usage with and without arguments, and even positions the tool within the broader ecosystem by mentioning meta-tools, making it fully sufficient for an onboarding 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 schema already covers the topic parameter at 100%, so the baseline is 3. The description adds meaningful nuance by stating that omitting topic returns the full spread and provides concrete examples like 'finance', 'pharma', and 'betting' that reinforce the parameter's purpose, going beyond the schema description.

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

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

The description clearly identifies the tool as the onboarding entry point for suggesting example questions, and details what it returns: category-bucketed questions with exact tool and argument shapes. It distinguishes itself from siblings like discover_tools by focusing on 'what can I ask' and specifically mentions 'Use this FIRST' for new agents.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit the topic parameter versus providing a focus area, giving clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond restating the resource. It does not mention what happens if the ID is not found, whether the result is a full record or summary, or any side effects beyond what annotations imply.

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, front-loaded sentence with no filler. It is appropriately concise for a simple lookup tool, though it borders on under-specification. Every word serves a 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?

The tool is simple, has robust annotations, and an output schema exists, so the description need not explain return values. Still, it lacks usage guidance and any context about what a 'target record' contains or when to use this tool over siblings. It is minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does state that the parameter is a 'ChEMBL target ID', which adds some meaning beyond the property name 'chembl_id'. However, it provides no format, example, or constraints. Given only one parameter, the added value is marginal.

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 'Target record by ChEMBL target ID' identifies a specific resource (ChEMBL target) and the identifier type used. It clearly separates this tool from siblings like 'molecule' or 'mechanism'. The verb 'Target' is slightly ambiguous (could mean 'the target record' vs 'to target'), but the meaning is clear in context.

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?

There is no guidance on when to use this tool versus alternatives. It simply states the function without mentioning prerequisites, excluded scenarios, or sibling tools. The agent receives no explicit direction for selecting this over 'molecule' or 'entity_profile'.

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

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

Annotations already indicate a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds valuable nuance: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This goes beyond annotations by explaining the soft-delete mechanism.

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

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

Two sentences with no redundancy, front-loaded with the core action. Every sentence adds meaningful context: the action, ownership, and the consequence of cancellation.

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

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

Given the low complexity (one parameter, no output schema) and rich annotations, the description covers purpose, ownership, and post-cancellation behavior. It fully equips an agent to decide when and how to 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?

The input schema fully documents the single id parameter as 'Subscription id (uuid) returned by subscribe.' The description adds the ownership requirement but no additional parameter-level detail. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by emphasizing ownership enforcement and the soft-delete behavior.

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

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

The description implies when to use the tool (to cancel a subscription) and adds an ownership constraint. It does not explicitly name alternatives or exclusions, but the context of sibling tools and the mention of recent_alerts provides some direction.

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 non-destructive behavior. The description adds meaningful behavioral context beyond annotations: the SEC EDGAR+XRBL fast path for financial claims, fall-through to a grounded pipeline, output verdicts, and the performance benefit of replacing 4-6 sequential calls. 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 dense but well-organized: trigger phrases first, then core purpose, routing logic, outputs, and performance note. Every sentence earns its place, though it is on the longer side. A slightly tighter structure could improve scannability, but overall it is 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?

There is no output schema, so the description appropriately details the return value (verdict, actual value, citation, reasoning). It also covers the tool's complex routing behavior. Annotations cover safety aspects. No critical gaps are apparent, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by providing concrete examples for the claim parameter and offering guidance for tolerance_pct (e.g., 'set 1–2 for hallucination detection'), which goes beyond the schema's existing description. 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?

The description clearly states it performs natural-language claim verification with specific verb and resource ('natural-language claim verification against authoritative sources'). It is distinguished from siblings like ask_pipeworx and deep_research by the fact-checking scope and inclusion of trigger phrases ('fact check', 'verify the claim that...'), leaving no ambiguity about its function.

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 the agent needs to check whether something a user said is factually correct' and explains the routing logic for financial vs. non-financial claims. However, it does not explicitly name alternative sibling tools or state when NOT to use it, so it falls short of a perfect score.

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