Protein Atlas

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

Beyond the readOnly and idempotent annotations, the description adds critical behavioral details: return structure (per-model score/confidence/signals/raw_response + combined view), cost implications (Anthropic calls are BYO key), and that Workers AI is free. 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 three sentences, front-loaded with the main action and purpose. Every sentence earns its place: probe and score, default model and key usage, and example use cases. No fluff 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?

Despite having no output schema, the description adequately covers return values (per-model score/confidence/signals/raw_response + combined view). It explains all four parameters, their roles, and typical use cases. No apparent gaps given the tool's simplicity.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the default model (Workers AI), that _apiKey enables Anthropic, and that context helps disambiguate. This goes beyond the schema's 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 verb (probe), resource (LLMs), and outcome (score visibility 0-100). It distinguishes itself from sibling tools by focusing on AI visibility audits for brands/products, which is unique among siblings like ask_pipeworx or scan_competitor_ai_presence.

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 contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and specifies when to use which models (default Workers AI, Anthropic requires _apiKey). It does not explicitly compare to siblings or state when not to use, leaving some room for ambiguity.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful context beyond that: it is an auto-routing tool that fills arguments, uses verified sources, and returns citation URIs. It does not discuss failure modes or limits, but the safety profile is covered by annotations and the routing/citation behavior is a useful 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 front-loaded with the most important instruction and includes useful examples and sibling routing. However, it becomes a long run-on passage with grammar issues, repeated ideas, and confusing fragments such as 'for an answer spanning many entities with cutoffs and recency aware, use bet_research for maneuver-weighted scenarios.' Some sentences, like 'There is also the beta variant ask_pipeworx_beta', add little structural value.

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

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

For a router tool with one required natural-language parameter and no output schema, the description covers the core contract: when to use it, what it does internally, what it returns, and how it compares to major siblings. It is largely complete, but the confusing alternative-routing sentences and lack of any mention of response format details beyond 'structured answer with citation URIs' keep it from being fully 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 100%, so the baseline is 3. All six parameters are aliases for 'question' and are described as such in the schema, and the description plus schema examples make clear that a natural-language question is expected. There is no additional depth about input formatting, length, or language constraints, but the schema already carries the necessary 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 states a specific core function: it routes questions to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This clearly distinguishes the tool from generic web search and from sibling research tools like deep_research or validate_claim.

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

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

The description explicitly says to prefer this tool over web search for factual/current-data questions, lists many covered domains, gives trigger phrases, and names alternatives such as ask_pipeworx_grounded, deep_research, validate_claim, and compare_entities. However, the routing guidance is muddled by typos and confusing references like 'single:ask_pipeworx' and 'Use for single-answer funnel: deep_research', which reduce its reliability.

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 explaining the beta nature, that candidates are toggled live, that none is currently active, and that it is a fully working router rather than a fallback. It also clarifies the comparison/merge workflow with the stable router. The annotations already provide readOnly/openWorld/idempotent hints, and the description adds meaningful behavioral context without contradicting them.

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

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

The description is dense but purposeful, front-loading the beta identity and matching behavior, then routing guidance, then the no-candidate status. Slightly verbose but every sentence earns its place by clarifying what 'beta' actually means operationally.

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 this is a single-string-parameter router with a full alias set in the schema and clear annotations, the description covers what an agent needs to invoke it correctly: what it is, how it differs from the stable version, current active state, and the fact that it is fully functional. It doesn't explain the response shape, but the description explicitly says the response shape is identical to ask_pipeworx, and there is no output schema. Minor gap: it doesn't enumerate sibling alternatives for when NOT to use it beyond ask_pipeworx, but the universal-router framing covers that.

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% for the single required question parameter and its five aliases, and the description adds that it takes 'the same arguments' as ask_pipeworx. The description doesn't add new parameter-level detail beyond the schema, but the schema fully documents the parameter. Baseline 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router that is functionally identical to the stable version. It distinguishes itself from the sibling ask_pipeworx by explaining it is the experimental edge with candidate routing improvements, and it explicitly names the stable counterpart. The verb 'ask' plus 'universal router' and the full explanation of its current behavior make the 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 explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It also states that no candidate is active right now, so it currently matches ask_pipeworx exactly. This gives an agent clear guidance on when to select this tool over its sibling.

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 the description adds substantial behavior beyond that: the refusal mechanism with its exact refusal_reason enum ('not_in_source'|'no_tool_match'|'tool_error'|'data_truncated'|'llm_error'), the full success response shape with verbatim evidence, and the extra LLM call cost. This is rich, non-redundant disclosure, and it does not contradict the read-only 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?

Front-loaded with the core purpose in the first phrase, then proceeds in a logical order — mechanism, success return shape, refusal contract, usage guidance, cost tradeoff. Every sentence earns its place; there is zero redundancy despite covering a large amount of behavioral ground.

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 documents both the success and refusal response structures, which is the main missing-piece risk for a tool like this. Annotations cover the safety profile, the schema covers the one parameter, and the description covers routing scope, cost, and refusal semantics — nothing critical 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 schema fully documents the question parameter with six aliases, so the baseline is 3. The description adds complementary processing semantics: the question is routed across '5,798 across 1517 sources' and 'fills arguments,' telling the agent the single required parameter is a high-level natural-language request that will be decomposed automatically — meaning beyond the schema's alias list.

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

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

The description opens with a specific, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism ('EXTRACTS the answer using ONLY what the tool result contains'). It explicitly distinguishes itself from the sibling ask_pipeworx via 'Same routing as ask_pipeworx' plus the grounded-extraction difference, so an agent can tell them apart immediately.

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?

Gives explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also names the alternative and the deciding tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' Nothing is left to inference.

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

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

The description goes far beyond annotations by detailing behavioral traits: resolver contract (market_match_confidence, suggestions), parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market detection), illiquid spread warnings, and resolution-rule risk. These are not captured in annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint = false).

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 comprehensive but lengthy; it covers many details in a dense manner. While front-loaded with the main purpose, the subsequent sections are somewhat verbose. It could be more concise without losing essential 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?

Given no output schema, the description thoroughly covers response shapes (market, analysis, evidence, resolver contract, parent event, news fields) and edge cases (low-confidence matches, closed markets, illiquid spreads, cancellation rules). This is complete for a complex tool.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining how to use each parameter (e.g., market accepts slug, URL, or question text; depth options; include_raw when to set true) and provides examples in the schema. This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies multiple input types (slug, URL, question text) and distinguishes itself from sibling tools by focusing exclusively on Polymarket bet research.

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

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

The description provides clear use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly name alternative tools, it implies when to use this tool over others, and the context is sufficient 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?

Beyond annotations (readOnlyHint=true, etc.), the description adds context: pulls latest 10-K from SEC, handles off-calendar fiscal years, returns sorted data by primary metric, includes 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?

The description is concise (~7 sentences) with front-loaded examples. Every sentence adds value, no redundancy.

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

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

Given the simple schema (2 params, no output schema), the description covers purpose, usage, data sources, sorting, and citations. It is fully sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds meaning by explaining what data is pulled for each type ('company' → revenue/net income/cash/debt; 'drug' → FAERS/FDA/trials) and specifies input formats (tickers/CIKs for company, names for drug).

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs' and uses verbs like 'compare' and 'rank'. It distinguishes from siblings by noting it replaces sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. This gives clear guidance on when to use this tool.

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, and the description adds substantial context: returns a findings packet with evidence, confidence, source, fetched_at, stable citations, explicit gaps[], contradictions[], and never-fabricated answers. It also documents second-hop depth behavior, semantic excerpting, citation resolvability, and timing expectations. 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 the length is earned for a complex tool. Critical constraints are front-loaded (account required, not open-web search, ask_pipeworx alternative), followed by behavioral details and timing. Every sentence adds useful decision-relevant information without meaningful redundancy.

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

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

With no output schema, the description carries the full burden of explaining return values and behavior — and it does so thoroughly. It explains what the findings packet contains, how gaps and contradictions are handled, how citations work, what depth levels do, how long to wait, and which sibling to fall back to. This is more than 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema with concrete example questions, clarifies that multi-part natural language questions are appropriate, and provides practical context on account requirements and latency for depth options. This pushes it above baseline, though the schema already carries most depth semantics.

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

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

The description clearly states the tool's job: grounded multi-source research across Pipeworx's structured data sources in one call. It explicitly contrasts itself with open-web search and names the sibling alternative (ask_pipeworx), while providing concrete example questions that make its scope easy to distinguish from siblings.

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

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

The description is explicit about when to use this tool (broad/multi-part questions over structured data) and when not to (single lookups should use ask_pipeworx). It also gives account-tier guidance, noting that non-signed-in users should use ask_pipeworx, and explains the depth modes' behavior and expected latency.

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. Description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is ready to call directly, providing useful 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 a single paragraph that efficiently conveys purpose, usage, and output. It is front-loaded with the main verb and resource. Could be slightly more structured but is not overly 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?

For a discovery tool with 6 parameters and no output schema, the description covers purpose, when to use, what it returns (including schemas and examples), and that results are immediately usable. This is sufficiently complete given the tool's simplicity.

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

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

Schema coverage is 100% with all parameters described. The description adds value by providing examples of natural language queries and noting that 'query' accepts aliases (task, q, description, search), which helps the agent understand how to construct the 'query' parameter effectively.

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 'Find tools by describing the data or task' and lists numerous specific data domains (SEC filings, financials, etc.), making the purpose crystal clear and distinguishing it from sibling tools like deep_research or entity_profile.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set'. This provides clear when-to-use guidance, though it could mention when not to use (e.g., if you already know the specific tool).

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

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

The annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds substantial behavior beyond that: fan-out across nine sources, GDELT→GNews fallback, 'an empty section is a real no-data, not a bug', the expected-empty fda_products caveat for small-molecule-only companies, and resolved:false-with-notes for private companies. This directly prevents false bug reports and misread 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 content is dense and every major clause earns its place, but it is one long run-on paragraph with a semicolon-heavy structure that hurts scannability. The six trigger phrases at the top are redundant — two would have conveyed the same signal — and the type-interchangeability note repeats what the schema already states. Front-loaded purpose is good, but the formatting is not appropriately sized.

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 high-complexity tool with no output schema, so the description must carry the burden of explaining return values — and it does, enumerating every result section (cik/company_name, recent_filings with URIs, fundamentals, patents, contracts, fda_products, hiring, news, LEI, sources_used/sources_failed) plus error/edge semantics. Given its complexity, nothing an agent needs to invoke it correctly or interpret its results 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?

Schema coverage is 100%, with the enum behavior and the ticker/CIK/name formats already fully documented in the input schema, so the baseline is 3. The description mostly restates these formats with examples, adding only marginal extra value: resolved_from/resolved_to when `value` was a name and the private-company resolution outcome. It does not add format or syntax 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?

States a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call', with six concrete trigger phrases that leave no ambiguity about what the tool does. The 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' line differentiates it from the single-query siblings without needing to open any 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?

Explicitly says when to prefer this tool ('when the user asks for a holistic view') and what to use instead (chaining single-pack lookups). It also enumerates the three accepted input shapes (ticker, CIK, company name) and the boundary case (private company → resolved:false), so an agent can route accurately before invoking.

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 destructiveHint=true and readOnlyHint=false. Description reinforces by stating 'Delete' and adds specific use cases like clearing sensitive data, providing extra 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?

Two sentences, no wasted words. Front-loaded with action and resource, then usage and companions.

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

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

Given simple tool (1 param, no output schema), description covers purpose, usage, and relation to siblings completely.

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

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

Schema coverage is 100% with clear description 'Memory key to delete'. Description adds 'by key' and shows example, but schema already does heavy lifting – adequate but not extra.

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

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

Clearly states 'Delete a previously stored memory by key' – specific verb and resource. Distinguishes from siblings by framing as deletion counterpart to remember and recall.

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

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

Explicit usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' Also names alternative tools (remember, recall) for context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destruction. Description adds that the tool fetches the page and extracts data, but no new behavioral traits beyond annotations.

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

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

Three sentences: purpose, process, usage. Front-loaded with key information, no wasted words.

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

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

Given no output schema, description explains output format (markdown, single text blob) and usage. Covers what a user needs to know to invoke and understand the result.

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

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

Schema coverage is 100%, so description adds minimal value—only restates parameter purposes. Baseline 3 is appropriate as schema already documents both parameters.

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

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

Clearly states the tool generates a production-ready llms.txt file for any URL, specific verb+resource. Distinguishes from sibling tools like ai_visibility_check by focusing on file generation.

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 lists three use cases: indexing client sites, drafting for own project, auditing competitors. Does not state when not to use, but scenarios are clear and helpful.

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, conveying that the tool is safe and idempotent. The description adds behavioral context by stating the tool returns a 'trimmed' profile (implying a subset of data), listing the specific fields, and noting 'Keyless' (likely meaning no authentication required). This adds value beyond the annotations.

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

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

The description is extremely concise: two sentences that front-load the purpose with the verb 'Get'. It wastes no words and includes a code example and a usage hint. Every sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It enumerates the return fields and mentions keyless access. There are no obvious gaps for a user to understand input, 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% for the single parameter 'ensembl_id', so the schema already documents it fully. The description adds an example ID ('ENSG00000146648') which helps illustrate the format, but does not provide additional semantic meaning. According to guidelines, baseline is 3 when coverage is high, and the example is a minor improvement.

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 action ('Get') and the resource ('trimmed Human Protein Atlas profile for one protein by Ensembl gene id'). It lists the specific data fields returned and provides an example Ensembl ID, making the tool's purpose unmistakable. It also distinguishes itself from the sibling tool 'search_genes' by directing users to use that tool to find the Ensembl ID.

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 using 'search_genes' to find the Ensembl ID, providing a clear alternative for discovery. However, it does not specify when not to use this tool or other potential alternatives beyond that. For a simple lookup tool, this level of guidance is sufficient but not exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's subscriptions, confirming the read-only and safe nature.

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: first states purpose and return fields, second gives usage guidance. No fluff, every sentence earns its place.

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

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

For a simple list tool with one optional parameter, the description adequately covers purpose, behavior, and return values. Lacks information on pagination or limits, but given the tool's simplicity and the fact that annotations and schema cover safety and parameters, it is sufficiently complete.

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

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

The single parameter 'include_inactive' has 100% schema description coverage, so the description does not need to add context. Baseline 3 is appropriate as per guidelines; the description neither adds nor detracts from parameter understanding.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe and unsubscribe. It also enumerates return fields, leaving no ambiguity about the tool's function.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it does not explicitly mention scenarios where this tool should be avoided in favor of 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 provide no safety hints (all false), so the description carries the full burden. It discloses key behavioral traits: anonymous filing returns a claim_token, passing it later retrieves resolution status, digests are read daily, and there's a rate limit ('Rate-limited to 5 per identifier per day'). It also clarifies that feedback is free and doesn't count against tool-call quota. 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 serves a distinct purpose: it defines the tool, gives usage triggers, marks scope boundaries, explains the claim_token mechanism, mentions rate limits, and clarifies cost. It is front-loaded with the core purpose and then unfolds into operational detail with no empty 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?

Despite having no output schema, the description explains return behavior (claim_token) and the follow-up flow. It covers all key operational facets: what to report, what not to report, domain restriction, rate limit, and post-filing interaction. The nested context object is given schema-level detail, and the description ties the parameters together coherently.

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 each parameter has a description. The tool description supplements this by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and advising users to describe issues in terms of Pipeworx tools rather than pasting the end-user prompt. This adds behavioral context to the parameters beyond the raw schema, exceeding the baseline of 3.

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

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

The description opens with a clear, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the resource (feedback to Pipeworx team) and directly distinguishes from sibling research/inquiry tools like ask_pipeworx by framing itself as a feedback channel. It also enumerates typical reasons (bug, feature gap, praise) which instantly clarifies when to invoke it.

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 a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It provides a critical exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server ... file it with that server instead.' This is a model example of when-to-use/not-use guidance.

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

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

Annotations already mark as read-only, safe, and idempotent. Description adds valuable behavioral details: self-aggregating from CF analytics engine, no PII, cached 5min-1h depending on window. 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?

Three sentences, front-loaded with main purpose, each sentence adds value (return data, use cases, caching/details). No wasted words.

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

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

Simple read-only trending tool with one optional parameter. Description covers return content, time windows, caching behavior, and use cases. No output schema needed; description sufficiently complete.

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

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

Schema covers parameter fully with enum and description. Description adds semantic guidance on window selection (short vs long demand). Adds meaning beyond schema for the parameter's purpose.

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

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

Clearly states it returns top tools, top packs, and call volume over recent windows. Verb 'returns' + resource 'trending data' is specific. Distinct from sibling tools like 'discover_tools' or 'search_within' by focusing on aggregated call data.

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

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

Lists three concrete use cases: discovering hot data sources, confirming canonical tools, checking alignment with agent needs. Provides window selection guidance (shorter for hot, longer for steady-state). Lacks explicit when-not or alternatives, but context is clear.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior; description adds context about response structure, fill check, placeholder filtering, and semantic anchor, with no contradiction.

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

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

Front-loaded with purpose, but includes extensive detail that could be slightly trimmed. However, it is well-organized with clear mode descriptions.

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

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

No output schema, yet description fully explains return values (opportunities, partition_check, fill check) and edge cases (placeholder filter, low similarity). Complete for a complex 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%; description enriches meaning with examples of event slugs, topic seeds, URL acceptance, and explains the scanning logic for each parameter.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between event mode, topic mode, and default trending scan, differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly guides when to use event vs topic modes, and that no args gives trending scan. Includes warnings for when not to trade (realizable_edge_pp ≤ 0) and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations already indicate readOnlyHint=true (safe read operation) and destructiveHint=false. The description adds extensive behavioral detail: the three model families, edge calculation methodology, caching (1h at KV level), and diagnostics like filter_skips. This goes well beyond what annotations provide, offering full transparency into how the tool operates and handles edge cases.

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 and well-structured, starting with purpose, then segments, parameters, and diagnostics. While it is long, it avoids redundancy and every sentence adds value. It could be more concise, but the density 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and the fields within each opportunity (edge_pp_net, kelly_fraction, etc.). It also covers tradeable-edge knobs and caching. Given the high parameter count and model complexity, the description is very 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% (all 9 parameters have descriptions). The description adds significant value beyond schema by explaining parameter usage in context, e.g., slippage_pp includes Polymarket fee details and recommendations for different scenarios, and min_partition_leg_kelly explains when to use it. This helps agents select and set parameters correctly.

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

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

The description clearly states the tool's purpose: scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and action (scan and return opportunities), and the phrase 'Built for what should I bet on today' clarifies its intended use. It also distinguishes from sibling tools by detailing unique model families and segments.

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

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

The description provides context on when to use the tool ('what should I bet on today', 'agents discover opportunities without paging hundreds of markets') and explains its caching behavior and parameter knobs. While it doesn't explicitly mention alternatives or when not to use, the detailed context is sufficient for an agent to understand its applicability.

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 safe, read-only behavior. The description adds transparency about data sources (daily snapshots), time limits (60-day TTL, start of snapshotting), and that decay values are computed from daily closes. No contradiction with annotations.

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

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

The description is front-loaded with a clear question and is packed with useful details. Some elements like the sign explanation could be streamlined, but overall every sentence adds value.

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

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

Given the complexity of edge tracking with time series and no output schema, the description thoroughly covers the response structure (tracked, expired, snapshot_dates), limits, and data semantics. It leaves little ambiguity.

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

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

Schema coverage is 100%, and the description adds meaning by explaining the 'days' parameter's default and max values, and the 'window' parameter's role as a snapshot family. This goes beyond just restating schema fields.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical time-series analysis.

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

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

The description explains the use case (comparing fresh vs. old edges) and provides parameter defaults, but it does not explicitly state when not to use this tool or mention alternatives for similar tasks. It gives usage context but lacks exclusion criteria.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context: walks the order book ladder, returns fill details and verdict, and for baskets warns about forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is dense but well-organized with clear mode separation and bolded key terms. Every sentence adds value, though it could be slightly more concise without losing critical detail.

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

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

Given no output schema, the description thoroughly enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) for both modes, covers edge cases like partial fills and forced directional risk, and is complete for a risk-check tool with four parameters and complex behaviors.

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

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

Schema coverage is 100%, so baseline 3. The description adds significant meaning: explains how size_usd is interpreted differently for single-market vs basket, default for side, and that exactly one of market or event is required. Provides context beyond schema, such as clamp ranges and auto-detection for basket side.

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 a 'realizable-vs-theoretical edge check' against order book depth, distinguishes single-market and basket modes, and explicitly notes its prerequisite for arb signals or large trades, differentiating from siblings like 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?

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial basket fills convert arb into unhedged position), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description goes far beyond this by disclosing nuanced behavior: compatibility codes, pairing-unverified caveats, unclassified-leg exclusion rules, fee modeling limitations, skipped comparison counters, and the meaning of null temporal_alignment. It also warns that a non-empty compatibility warning can coexist with matched pairs. This is exemplary 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 long and dense, but it is well-structured with clear section labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. Every major block serves a functional purpose, and the opening sentence immediately states the core purpose. It loses a point for being somewhat sprawling and for using prose where a tighter bullet structure could reduce cognitive load, but it remains organized and information-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?

There is no output schema, so the description carries the full burden of explaining the response shape and interpretation. It covers the response structure, safety fields, flag semantics, fee disclosure, skipped-pair counters, and the meaning of null alignment. For a tool with this complexity, the description is remarkably complete and leaves little to guesswork.

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, but the description adds substantial meaning beyond the schema. It explains the topic shortcuts, the auto-fetch behavior, the override semantics for `kalshi_event_ticker` and `polymarket_event_slug`, and the fact that both modes run the same token-overlap matcher. This gives an agent the conceptual model needed to invoke the tool correctly.

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

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

The description opens with a precise statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource, the operation, and the cross-venue nature, which helps distinguish it from the single-venue Polymarket-focused sibling tools. It also lays out the two operational modes, 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 clearly explains when to use the `topic` mode versus explicit `kalshi_event_ticker` + `polymarket_event_slug` mode, and warns that most pre-mapped topics currently return compatibility warnings. However, it does not explicitly compare against sibling tools such as `polymarket_arbitrage` or `polymarket_edges`, so there are no explicit 'use this instead of X' exclusions. The context is clear but the alternatives are not named.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping by identifier and clarifies behavior when key is omitted, providing context beyond annotations.

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

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

Three sentences, each adding value. The core action is front-loaded. Could be slightly more concise but not wasteful.

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 read tool with one parameter and strong annotations, the description covers usage, scoping, and related tools. No output schema but return values are 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 single optional parameter. The description repeats the behavior ('omit to list all keys') but does not add new meaning 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 retrieves a value saved via 'remember' or lists all keys when omitted. It uses specific verbs ('retrieve', 'list') and distinguishes from sibling tools '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?

The description provides use cases (look up context like ticker, address, notes) and mentions pairing with 'remember' and 'forget'. It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. Description adds behavioral context about return fields, mark_read effect, and feed persistence, without contradiction.

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

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

Single, well-structured paragraph front-loaded with purpose. Every sentence adds value without redundancy.

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

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

Despite no output schema, description specifies return fields and alternative access. All parameters are explained. Complete for a tool with five optional parameters.

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

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

Schema coverage is 100%, but description adds interpretation: example type 'sec_8k', explains mark_read and unread_only behavior, and clarifies limit range implied.

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 pulls fired events from the subscription feed, returning the most recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from siblings by mentioning an alternative access method via GET endpoint.

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 guidance on filtering by type and/or ISO timestamp, using mark_read for read tracking, and that polling works fine. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations indicate readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds substantial behavioral context: fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), describes soft-fail for patents sunset, and mentions return structure (changes[], total_changes, citation URIs). No contradictions.

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

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

Description is a single dense paragraph that packs examples, source details, fallback logic, and parameter guidance efficiently. Could be slightly better structured with bullet points, but the front-loaded examples make it highly 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?

Given no output schema, the description adequately describes return structure (changes grouped by source, total_changes, citation URIs). It covers all required parameters, supported values, and fallback behavior. A minimal mention of the exact shape of changes[] would be helpful but not essential.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value beyond schema by explaining accepted date formats ('2026-04-01', '7d', '30d', '3m', '1y'), suggesting '30d' or '1m' for typical monitoring, and clarifying value can be ticker or CIK. Slightly more detail than schema, but schema already covers basics.

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 aggregates changes (SEC filings, news, patents) for a company over a time window, using examples like 'what's new with X'. It distinguishes from sibling 'entity_profile' by noting that tool is for static profiles regardless of window.

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 provides example queries for when to use ('What's new with X', 'latest on Y') and explicitly directs to 'entity_profile' for static profiles, giving clear when-not-to-use guidance.

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

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

Discloses scoping by identifier, persistence (authenticated vs anonymous 24h), and idempotent behavior. No contradiction with annotations (readOnlyHint=false, idempotentHint=true). Adds value beyond structured data.

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

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

Concise and well-structured: starts with purpose, then usage, then behavior. Every sentence adds value; no waste.

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?

Complete for a simple key-value tool. Explains scope, persistence, and relationship with sibling tools. No output schema needed; description suffices.

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

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

Schema covers parameters fully (100% coverage). Description does not add param-specific semantic details beyond schema, so baseline 3 is appropriate. The contextual info about scoping is useful but not param-specific.

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?

Purpose is clear and specific: 'Save data the agent will need to reuse later.' Distinct from siblings recall and forget, and uses a verb-resource pattern (save data) with explicit scope.

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

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

Provides explicit guidance: 'Use when you discover something worth carrying forward' with examples (ticker, address, preference). Mentions pairing with recall and forget, giving clear 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 cover readOnlyHint, idempotentHint, and destructiveHint, so the description adds value with behavior beyond safety: graceful degradation ("if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return"), internal multi-endpoint cascading, and conditional ownership data ("parent/ultimate-parent/children ownership when the LEI resolves"). It stops short of describing behavior on total lookup failure.

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 purpose is usefully front-loaded and every sentence carries information, but the company-type segment is a multi-clause run-on with nested parentheticals (SEC EDGAR / GLEIF / OpenFIGI / NON-EQUITY instruments / ISIN mapping) that is difficult to scan. The description is near the upper bound of acceptable length for an agent-facing definition.

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 two-mode tool with no output schema, the description specifies per-type return contents (CIK/ticker/company_name/LEI/FIGI for company; RxCUI/ingredient/brand/citation for drug), accepted inputs, and partial-failure behavior, which covers most of what an agent needs. The remaining gap is the unspecified behavior when no identifier resolves at all.

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 ISIN as an accepted input form not present in the schema and clarifies resolution semantics ("an ISIN like CH0038863350 resolves to the LEGAL ENTITY that issued the security"). The critical anti-misuse warning about passing the full noun phrase lives in the schema's value description, so the description itself adds a moderate but useful increment.

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 precise verb+resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input" and enumerates the two supported types ("company", "drug") with their distinct outputs. It also orients the agent with "Use FIRST whenever you have a name but need an ID", which separates it from siblings like entity_profile or compare_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?

It gives explicit when-to-use guidance — "Use FIRST whenever you have a name but need an ID" — and documents accepted input formats (ticker, CIK, ISIN, company name, brand/generic drug name). It does not name alternatives for the case where an ID is already held, so the when-not-to-use side is only implied.

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 behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with detailed fields (score, confidence, signal density). This exceeds what annotations provide and ensures full 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?

Two sentences, front-loaded with the core action, no fluff. Every sentence serves a purpose: stating what it does, how it works, and the output format. This is model conciseness.

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 4 parameters, no output schema, and annotations that cover safety, the description is remarkably complete: it describes the input (entities + optional params), the internal process (probes with ai_visibility_check), the output format (ranked list with score/confidence/signal density), and the use case. Nothing essential is omitted.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains that the first entity in 'entities' is treated as the 'subject' for narrative, and that 'context' disambiguates common names. This extra value 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 uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly identifies the resource (AI visibility across multiple entities). It explicitly distinguishes from siblings by stating it uses ai_visibility_check and targets competitive audits, making its purpose distinct from ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description provides clear context for use ('competitive AI-marketing audits') and implies when to use this over ai_visibility_check (for multi-entity comparison). However, it does not explicitly name alternatives or state when not to use it, stopping short of the 5-point bar.

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

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

The description adds significant behavioral context beyond annotations: partial failure handling, timing (5-30s for bundlephobia first measurement), and graceful degradation with 'sources_failed' listing. 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 informative but slightly lengthy. However, it is well-structured with key points front-loaded and no redundant sentences. Could be more concise but still effective.

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 thoroughly explains what the tool returns (summary block, per-advisory detail, links, alternative versions). It also covers failure modes and timing, making it complete for the agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by mentioning scoped packages ('@types/node' accepted) and implying default behavior, but the schema already states defaults. A small additional benefit.

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

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

The description clearly states it performs a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying the NPM ecosystem and mentioning alternatives for other ecosystems.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also clearly denotes when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already indicate this is read-only, idempotent, and non-destructive. The description adds that it is 'Keyless' (no authentication needed) and lists the returned fields, providing some additional context but not significantly 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?

Two concise sentences: first states the purpose and data source, second lists key output and notes it's keyless. No 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 search tool with good annotations and full schema coverage, the description adequately covers the purpose, input, output, and access requirement. It could mention pagination or default limit, but the schema already handles that.

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

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

Schema coverage is 100% with descriptions for both parameters (query, limit). The description mentions 'by gene symbol or keyword' which aligns with the query parameter description, but adds no extra meaning 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 it searches the Human Protein Atlas for human genes/proteins by gene symbol or keyword, and specifies it returns Ensembl gene id, synonyms, and description. This distinguishes it from sibling tools like get_protein and top_tissues that require the Ensembl id as input.

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 this tool is a prerequisite for get_protein and top_tissues by stating the returned Ensembl id is needed by those tools. However, it does not explicitly provide guidance on when to use vs. alternatives or 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?

Beyond annotations (readOnly, idempotent, openWorld), description adds embedding model details, window size, character offsets, similarity scores, and the 200K char cap with truncation flag. 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 plus a technical note. Front-loaded with core idea, every sentence adds value. No wasted words.

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

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

Covers all aspects: purpose, usage, parameters, behavior, limits, result details, and sibling relationship. Complete for an agent to correctly invoke despite lack of 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?

Schema coverage is 100%, but description adds value: examples for query, clarifies default for limit, and reiterates text cap. Exceeds baseline by providing usage context.

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 semantic search inside a fetched record, using a verb+resource structure. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing context-saving.

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

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

Explicitly tells when to use (record too big for prompt) and provides an alternative pattern (pair with ask_pipeworx_grounded). Gives concrete use case examples.

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 idempotent and non-destructive. The description adds behavioral context: OAuth requirement, phone verification, SMS cap (10/day), webhook signing, and that webhook secret is returned once. No contradictions.

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

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

The description is moderately long but well-structured and front-loaded. Every sentence adds value, though some details (e.g., webhook signing) could be more concise. Overall efficient for the complexity.

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

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

Given the tool's complexity (multiple types, delivery options, prerequisites), the description covers most aspects. It lacks explicit return value format beyond subscription ID, but annotations and schema mitigate this.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds richer semantics: concrete examples for each type (e.g., items:['5.02'] for sec_8k), and delivery channel details beyond schema (e.g., phone verification, cap, webhook HMAC).

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 action: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the resource (subscription) and distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description provides explicit when-to-use guidance, prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channels. Implicitly, it contrasts with 'list_subscriptions' and 'unsubscribe' for other operations.

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, covering safety. The description adds behavioral details: returns example questions with exact tool+argument shapes, drawn from a live catalog. No contradictions.

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

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

The description is somewhat lengthy but each sentence contributes useful information. It front-loads the purpose and provides a clear structure. Could be slightly trimmed, but it's efficient for an onboarding tool.

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

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

For a simple tool with one optional parameter and no output schema, the description is comprehensive. It covers when to use, how to use, what it returns, and its role in the ecosystem.

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

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

Schema description coverage is 100%, but the tool description adds significant value by listing possible values for the topic parameter and explaining behavior when omitted. This goes beyond the schema's brief 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 states the tool's purpose: returning category-bucketed example questions to help users learn what to ask Pipeworx. It uses specific verbs like 'returns' and 'use this FIRST', and distinguishes it from siblings by positioning it as the onboarding entry point.

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

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

Explicitly says to use this tool first when unsure about Pipeworx's capabilities, and explains how to call with no arguments for a full spread or with a topic for focus. It also mentions learning how to call meta-tools, providing clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that results are ordered 'highest first', data source is 'RNA expression (nTPM)', and notes 'Keyless' for no authentication. No contradictions with annotations.

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

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

Two sentences, front-loaded with the main action. Every sentence adds value: first describes the tool, second gives usage guidance and notes keyless. 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?

No output schema exists, and the description does not specify the format of the returned list (e.g., fields like tissue name and nTPM value). It implies human tissues only. Adequate but incomplete for a read 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 has 100% coverage for both parameters, including default for limit. Description does not add significant meaning beyond the schema; it mentions ordering but that is not parameter-specific. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'a protein's top-expressing human tissues by RNA expression (nTPM)' for one Ensembl gene id. It mentions search_genes as a prerequisite but does not explicitly differentiate from sibling 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 advises to use search_genes to find Ensembl id before using this tool. Provides clear context for when to use, but no explicit when-not-to-use statements.

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 show readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds critical context: the row is deactivated not deleted, and historical events remain available via recent_alerts. This exceeds what annotations provide, with no contradiction.

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

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

Three sentences, each adding value: what it does, ownership constraint, and deactivation behavior. No waste, perfectly structured.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the action, constraints, and post-call behavior (deactivation, historical availability). No gaps.

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

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

Schema coverage is 100% and the only parameter 'id' is described as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id'), identifying the verb (cancel), resource (subscription), and key identifier (id). It also distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancellation action.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions'), providing a clear condition for when the tool is applicable. It implies when not to use it (e.g., another user's subscription) but does not explicitly name alternative tools.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, and destructive=false, but the description goes well beyond them by explaining the routing logic, the verdict types (confirmed, refuted, etc.), the inclusion of verbatim evidence and a citation, and the critical caveat that 'could_not_verify' is not evidence for or against the claim. This adds significant behavioral context not inferable from annotations.

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

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

The description is long but densely packed with essential information: example phrases, use-case, routing, return values, caveats, and efficiency note. It is well-structured with semicolons and dashes, but could be slightly tighter without losing meaning. However, every sentence contributes value, so it earns a high score.

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

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

Given two simple parameters and no output schema, the description is remarkably complete. It explains return verdicts, the actual value with citation, reasoning, the meaning of error states, the routing logic for different claim types, and the alternative to sequential calls. For a tool of this complexity, nothing essential 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 already has 100% coverage with descriptions for both parameters. The description adds extra nuance by explaining how tolerance_pct overrides the claim's implied wording tolerance, mentions the default cap of 5%, and recommends 1–2% for hallucination detection. This goes beyond the schema's bare numeric range, though it doesn't fully redefine the 'claim' parameter beyond the schema's 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 opens with concrete example phrasings and states the core function: 'natural-language claim verification against authoritative sources.' It clearly distinguishes the tool from siblings by specifying the fact-checking use case and the two distinct pipelines (SEC EDGAR for company-financial claims, grounded pipeline for anything else), which separates it from general-purpose tools like ask_pipeworx or deep_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates when the structured SEC path applies versus the grounded fallback, and warns about the meaning of 'could_not_verify' vs 'unsupported,' giving clear guidance on interpreting results. It also notes this replaces multiple sequential calls, reinforcing when to select it.

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