Chembl

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavior: it returns a specific set of fields, and for biologics it explicitly states the response will indicate no data rather than returning an empty list. This goes beyond the annotations and clarifies expected output.

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

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

The description is two sentences with no filler. The first sentence front-loads the action and key parameters; the second sentence adds a critical edge-case clarification. Every word earns its place.

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

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

The tool is simple (3 optional params, no required), has an output schema, and strong annotations. The description covers the tool's purpose, filters, return types, and an important edge case. This is sufficient for an agent to decide to invoke it and know what to expect.

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' is described). The description compensates by explaining that molecule_chembl_id and target_chembl_id are filters, and the word 'and/or' clarifies that either or both can be used. It does not add format details, but the semantic role is clear.

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 'Retrieve bioactivity records from ChEMBL filtered by molecule_chembl_id and/or target_chembl_id', which clearly states a specific verb and resource. It further specifies the returned data (IC50/Ki/EC50 values, assay descriptions, units) and distinguishes itself from sibling tools like chembl_mechanism, molecule, or target by focusing on bioactivity records with these filters.

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 (when you need bioactivity data for a molecule or target) but does not explicitly mention alternatives or exclusions. The note about small-molecule data provides context but not a direct comparison to other ChEMBL tools. There is no 'use this instead of X' guidance.

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

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

Beyond 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 mark the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by revealing the tool is a meta-router that fills arguments and returns stable piipeworx:// citation URIs, which is useful for expectation-setting. It does not mention latency or failure modes, but those are not critical 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 opening is strong and front-loaded, but the description ends with a broken repetition: 'START HERE for most questions — even if web search could also answer it. Examples: ...' duplicates earlier content and is incomplete. This redundancy and truncation make the structure noticeably messy.

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

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

Despite no output schema, the description tells the agent what to expect: a structured answer with stable citation URIs. It also conveys scope, 5,710 tools and 1,494 sources, and offers six examples, covering capability and typical use in one place. The lack of error/ambiguity handling details is a minor gap given the tool's router nature.

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

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

Input schema coverage is 100% and each of the six parameters is documented as an alias for question. The decription adds example queries but no new semantics beyond the schema's 'natural language' note, so schema carries the burden.

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

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

The description clearly states the tool routes natural-language questions to one of 5,710 verified-source tools and returns a cited structured answer, with an explicit 'PREFER OVER WEB SEARCH' directive. It does not, however, distinguish this tool from sibling variants ask_pipeworx_beta and ask_pipeworx_grounded, so it falls short of full differentiation.

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: 'Use whenever the user asks...' and 'START HERE for most questions', even when web search could answer. It includes a broad list of domains and example queries, but does not state when to avoid this tool or when to choose ask_pipeworx_grounded/deep_research instead.

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

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

Annotations already indicate a read-only, idempotent, non-destructive tool, but the description adds valuable context: candidate routing improvements are live only when under test, no candidate is currently active as of a specific date, and it is a full working router rather than a fallback stub. This is exactly the kind of experimental-state disclosure an agent needs.

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

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

The description is somewhat long but every sentence adds useful information: beta identity, identical scope, live-candidate behavior, current equivalence, usage instruction, and no-fallback clarification. It is front-loaded and avoids unnecessary repetition.

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 beta alias-style router, the description is complete: it explains the relationship to the stable tool, current behavior, experimental status, comparison purpose, and response shape. No output schema exists, but stating the same response shape as ask_pipeworx covers return expectations.

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

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

Schema coverage is 100%, with the question parameter and all five aliases already documented. The description only says 'same arguments' and does not add new meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear verb and resource: it is the beta version of ask_pipeworx, a universal router with the same tool set, arguments, and response shape. It explicitly differentiates itself from ask_pipeworx and ask_pipeworx_grounded by being the experimental edge used to test 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 explicitly tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It lacks an explicit when-not-to-use statement or a direct comparison against ask_pipeworx_grounded, but the intended usage is clear.

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

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

The description goes well beyond the annotations by disclosing the extraction-only behavior, the exact success and refusal response shapes, the possible refusal reasons, and the additional cost relative to ask_pipeworx. It also clarifies the open-world nature by acknowledging when the data does not directly answer.

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

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

The description is dense but every sentence adds decision-relevant information: behavior, return contract, refusal contract, use cases, and cost tradeoff. It is front-loaded with the core purpose and remains structured enough to scan quickly.

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 and the absence of an output schema, the description fully compensates by specifying the return shape, evidence field, confidence, source, fetched_at, and all refusal reasons. It also covers routing behavior, use-case fit, and cost, so nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% and the only semantically meaningful parameter, question, is already well documented with aliases. The description doesn't add parameter-specific detail, but the schema fully carries that load, so a 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 names a specific, behaviorally distinct mode: a hallucination-resistant, grounded answer extraction from tool results. It explicitly contrasts with ask_pipeworx by adding 'grounded' semantics, so an agent can distinguish it from the sibling tool without opening schemas.

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 this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete example domains. It also gives the alternative condition: prefer ask_pipeworx for casual lookups, plus the tradeoff of one extra LLM call.

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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive hints, and the description adds substantial behavioral context beyond that: account tier requirements, parallel decomposition across 5,710 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation), gaps[] never invented, contradictions[] for standard/thorough, semantic excerpting of large records, and latency expectations (15-60s, up to ~90s for thorough). No contradiction with annotations.

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

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

The description is long but every sentence carries essential information — auth requirements, tier restrictions, alternative tool, scope, internal mechanism, output format, gap/contradiction behavior, excerpting strategy, and latency. It is front-loaded with the most critical operational constraint (account required). A denser layout with bullets might improve scanability, but the content earns its place.

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

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

For a complex tool with no output schema and only two parameters, the description covers all needed context: authentication, cost, when to use alternatives, what the tool does internally, what the return packet contains, how gaps and contradictions are handled, and performance expectations. There are no obvious missing pieces an agent would need to decide whether and how to invoke this 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 schema already documents both parameters. The description adds meaningful semantic depth beyond the schema: it explains what the depth levels mean in practice (quick=3 facets single hop, standard=3 adds gap-recovery and contradictions scan, thorough=6 paid with full iterative hop), clarifies that thorough is paid, and clarifies that the question parameter accepts broad/multi-part natural language. This enriches the schema rather than simply repeating 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 clearly states the tool performs grounded multi-source research across 1,494 structured data sources in one call, explicitly distinguishing itself from open-web search and naming the sibling ask_pipeworx as the alternative for single lookups. It specifies a concrete verb (research/decompose/route) and resource (structured data sources), 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?

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead.' It also provides a conditional exclusion: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.' This is model guidance with clear alternatives and conditions.

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 already declare readOnly/openWorld/idempotent/non-destructive, and the description adds extensive behavioral disclosure beyond that: safety fields are present even on returned pairs, unclassified legs are never paired and are moved to skipped_unclassified, temporal_alignment is reported, and skipped_cross_type / skipped_cross_subtype counters explain what was dropped and why. It even calls out that pre-mapped ≠ tradeable. This is exceptionally transparent about edge cases and failure modes.

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 the tool is genuinely complex and has many safety flags and response fields that an agent needs to know. It is organized with caps-locked labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the core purpose before diving into details. A small amount of redundancy, such as repeating that pre-mapped topics often carry warnings, keeps it from a perfect 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?

Despite the absence of an output schema, the description fully covers the return shape: per-venue leg prices, matched spreads in percentage points, compatibility_warning, compatibility_codes, per-entry flags, skipped categories, low-confidence inspection pairs, and temporal alignment. Given the complexity of the tool and the lack of an output schema, this description is complete enough for an agent to call the tool and correctly interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description mostly restates what the schema already says about topic, kalshi_event_ticker, and polymarket_event_slug. It does add the context of 'custom pairings' and the auto-fetch behavior for topic values, but it does not meaningfully deepen the parameter semantics beyond the schema's existing descriptions. Thus a 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 names a very specific function — computing the cross-venue spread between Kalshi and Polymarket for the same resolving question — and distinguishes itself from the surrounding polymarket_* siblings by making the cross-venue nature and the exact direction of the spread explicit. The two modes (pre-mapped topic vs explicit ticker/slug) further pin down what the tool does. This is far from a tautology and leaves no ambiguity about the resource being operated on.

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 on when to rely on the pre-mapped topic shortcuts versus explicit Kalshi/Polymarket identifiers, and it warns that pre-mapped topics are not automatically tradeable and often return compatibility warnings. It does not, however, explicitly compare this tool against sibling alternatives such as polymarket_arbitrage or polymarket_edges, so the when-not-to-use guidance is stronger than the alternative-routing 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 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?

Even with annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context beyond those annotations. It explains graceful degradation: if GLEIF or OpenFIGI is unavailable, EDGAR identifiers still return. It also details that unresolved identifiers are listed explicitly under 'unresolved' rather than omitted, and that LEI/FIGI enrichment may degrade. These details are not inferred from the annotations alone.

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 packed with information and front-loaded with the most critical usage examples and guidelines. However, it is somewhat long (multiple sentences, some with parentheses-nested details that could be split into clearer lists). It earns its keep but could be slightly more scannable.

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

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

The description is fully self-contained for a tool with only 2 parameters, 100% schema coverage, and no output schema. It explains what each type returns, the graceful degradation behavior, and that it replaces multiple manual lookups. There are no obvious gaps given the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by giving concrete examples for each parameter (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company; 'ozempic, metformin' for drug). It also explains that for company, an ISIN resolves to the legal entity that issued the security, which goes beyond the schema's description. This additional context justifies a 4.

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

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

The description starts with example user queries that make the purpose instantly recognizable ('What's the ticker for...', 'look up the ID for...'). It then states the core action clearly: resolve a user-spoken NAME to canonical/official identifiers. The description also distinguishes between supported types ('company' vs 'drug') and lists what each returns, leaving 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 explicitly tells the agent when to use this tool: 'Use FIRST whenever you have a name but need an ID.' It explains it replaces 2-3 manual lookups, implying it is a preferred consolidation endpoint. It further lists the supported types and input formats (e.g., ticker, CIK, ISIN, company name, brand/generic drug name), giving clear guidance on when and how to invoke 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 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 declare readOnly, idempotent, and openWorld, but the description adds crucial behavioral semantics: the distinction between could_not_verify (check did not happen) and unsupported (no source), the requirement not to treat could_not_verify as evidence, and the two routing paths (SEC EDGAR structured vs grounded). No contradiction with annotations.

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

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

The description is long but every sentence carries operational value: trigger phrases, routing details, return format, error semantics, and replacement of multi-call workflows. It is well-structured, front-loading with examples and ending with practical notes, though slightly dense.

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

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

Despite having no output schema, the description fully specifies the verdict values, evidence format (grounded value + citation), reasoning output, and error handling. It also covers the two workflow paths and edge-case meanings, making the tool self-contained for an agent.

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

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

Input schema covers both parameters with detailed descriptions (100% coverage), including tolerance_pct defaults and override behavior. The description reinforces the tolerance meaning but does not add substantially new parameter-level semantics beyond what the schema already provides.

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

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

The description opens with explicit trigger phrases ('fact check', 'verify the claim that…') and clearly states the tool's function: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings like search and deep_research by scoping to factual claim checking rather than open-ended exploration.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing for company-financial vs other claims and notes the tool replaces 4–6 sequential calls. However, it does not explicitly name alternatives or state when NOT to use it (e.g., for broad research), 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.