Reactome

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 beyond that: the default model is free (Workers AI Llama-3.3-70b), using Anthropic requires a BYO key with direct costs to the user, and the output includes per-model details. There is no contradiction with the annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, then model options and output structure, and finally use cases. Every sentence contributes meaning without redundancy or fluff.

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

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

Despite having no output schema, the description explicitly lists the return fields per model (score, confidence, signals, raw_response) and mentions a combined view. It also covers cost behavior, default model, and practical use cases. For a 4-parameter tool with these annotations, this is fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema: it clarifies that `models` can be omitted for the default workers-ai, `_apiKey` is only needed if 'anthropic' is in models, and that providing a key incurs Anthropic charges. This enriches the parameter understanding beyond the raw field descriptions.

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

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

The description states the tool 'probes one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb ('probe') tied to a clear resource (LLMs about an entity) and output (visibility scores). It distinguishes itself from sibling tools by focusing on cross-model visibility scoring rather than general Q&A or entity resolution.

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

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

The description gives concrete usage contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' This clearly implies when to use the tool, but it does not explicitly name alternatives or exclusion criteria. Since no sibling alternatives are referenced, it stops short of the highest standard, 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that it routes to one of 5,767 tools, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. This gives the agent an accurate runtime model and matches the annotations without contradiction.

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

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

The the description is long and somewhat repetitious, but it is front-loaded with the most important routing instruction. Examples and domain lists earn their place by disambiguating acceptable queries for a very broad 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?

With no output schema, the description compensates by stating the return format, citation behavior, routing behavior, scope, examples, and alternatives. An agent deciding whether and how to call ask_pipeworx has the context it needs.

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

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

The input schema already provides 100% parameter coverage, including the primary 'question' parameter and five aliases, so the description does not need to repeat parameter mechanics. The description adds helpful examples but no additional parameter-specific semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a precise directive: prefer this over web search for current or historical factual data, and enumerates the exact domains covered. It clearly identifies the tool as a router that selects among thousands of source tools and returns cited structured answers, making its purpose unmistakable.

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

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

It gives explicit when-to-use guidance with trigger phrases like 'what is', 'look up', 'find', 'get the latest', and states it should be used even when web search could answer. It also names concrete alternatives and their conditions: ask_pipeworx_grounded for a single hallucination-resistant answer, and deep_research for broad multi-part questions.

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

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

Beyond the annotations, the description discloses important dynamic behavior: routing candidates are enabled live only when under test, none is currently active, and it is still a full working router rather than a stub. This directly shapes an agent's expectations about response variability and compatibility.

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 slightly longer than necessary, repeating that it matches ask_pipeworx and emphasizing it is not a stub. However, the critical facts (beta status, identical behavior, current inactive candidate, usage instruction) are front-loaded and each clause adds decision-relevant context.

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

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

With no output schema, the description compensates by saying the response shape is identical to ask_pipeworx, letting the agent consult the stable sibling for full details. It also covers current candidate status and fallback behavior. A precise return-format summary would be a minor addition, but the pointer to the identical sibling makes it 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 description coverage is 100%, so the parameters are already fully documented as aliases for 'question'. The description adds only that the arguments are identical to ask_pipeworx, which is useful for compatibility but doesn't enrich the parameter 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 identifies a specific resource (the beta edge of the ask_pipeworx universal router) and a specific behavior: it routes the same 5,767 tools with the same arguments and response shape. It also distinguishes itself from its stable sibling by stating it carries experimental routing candidates, so an agent can tell it apart from ask_pipeworx.

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

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

It explicitly tells the agent to use it 'exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It does not spell out when not to use it, such as a preference for the stable router in production, but the experimental-vs-stable contrast implies the boundary.

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

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

Annotations already mark it read-only, idempotent, open-world, and non-destructive, and the description adds substantial behavioral detail beyond that: it discloses the extra LLM call, the structured success return with verbatim evidence, and the explicit refusal contract with five enumerated refusal_reason values. There is no contradiction with the annotations.

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

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

The description is compact, front-loaded with the core purpose, and every sentence contributes either behavioral detail, use-case guidance, or a cost comparison. The return schemas and refusal reasons are embedded efficiently without wasted prose.

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

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

Although there is no output schema, the description fully specifies the success return shape and the refusal shape, including all possible refusal_reason values. Combined with the annotations and 100% parameter coverage, an agent has everything it needs to invoke the tool and interpret the result correctly.

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

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

Input schema has 100% description coverage by documenting all six parameters as aliases for question, so the schema carries the parameter semantics. The description adds useful context that the question is routed and used to fill arguments in other tools, but it does not need to restate the alias details.

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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and details the exact mechanism: route through 5,767 tools across 1506 sources, fetch data, and extract an answer only from the tool result. It clearly distinguishes itself from sibling ask_pipeworx by naming the extra evidence and refusal behavior and by noting the extra LLM call cost.

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 'Use whenever an answer will be quoted, cited, or acted on... when the agent must not invent facts' and lists use cases such as financial verdicts, legal claims, medical lookups, and public statements. It also gives the contrasting guidance to 'prefer ask_pipeworx for casual lookups' because this mode costs an extra LLM call.

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

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

Beyond the read-only/open-world/idempotent annotations, the description discloses extensive behavioral details: fan-out to category-specific data packs, resolver contract with market_match_confidence, parent_event extraction, news fallback fields (_fallback_attempted), safety short-circuits for low-confidence or closed markets, illiquidity flags, and resolution-rule risk parsing. No contradictions with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded purpose. Each section contributes functional details that help an agent use the tool correctly. While verbose, the organization makes it navigable and the length is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly documents return shapes (result.market, result.analysis, result.evidence), the resolver contract, parent_event extraction, safety statuses (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. It covers edge cases like GDELT 429s, wide spreads, and flat-50¢ void settlements, providing enough context 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?

The input schema already provides complete descriptions for all three parameters (market, depth, include_raw) with examples, defaults, and enums. The tool description repeats the market format and gives examples of depth's effect ('quick = 2-3 evidence sources') but adds no substantial meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), the action (research/pull data), and includes example use cases like 'should I bet on X'. It distinguishes itself from sibling tools that focus on arbitrage, edges, or tracking by concentrating on single-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 explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives concrete fan-out examples for various bet types. It does not explicitly name alternative tools for exclusion, but the context and examples make it clear when this tool is appropriate.

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

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

Annotations already declare readOnly/openWorld/idempotent safety. The description adds meaningful behavioral context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and citation URIs. It doesn't address limitations like latency or data availability, but the added context is solid.

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

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

The description is dense and front-loaded with query examples, but it is longer than strictly necessary. Every sentence contributes useful information, and the structure flows from usage to data details to output format, earning its length.

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

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

For a tool with no output schema, the description covers input constraints, data fields per type, sorting behavior, return format (paired data + citation URIs), and efficiency benefit. This is 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 coverage is 100%, but the description enriches both parameters: type is explained with per-enum data details, and values gets explicit examples, count constraints, and formatting guidance (ticker/CIK vs drug names). This goes well beyond the basic schema descriptions.

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

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

The description clearly identifies the tool as a side-by-side comparison for 2–5 companies or drugs in one parallel call, with concrete query examples ('X vs Y', 'rank these companies'). It distinguishes from sequential single-pack lookups by emphasizing 'ALWAYS PREFER' and 'Replaces 8–15 sequential lookups', and from sibling tools by specifying a unique comparison 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?

Explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides usage scenarios via example queries. It also clarifies the two modes (company vs drug) and what data each pulls, giving clear contextual guidance.

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

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

The description discloses far beyond annotations: account/tier requirements, parallel decomposition across 5,767 tools, the findings packet structure with citation_uri, explicit gaps[], contradictions[] for standard/thorough, semantic excerpting, latency expectations, and the 'never invented' guarantee. None of this contradicts the readOnly/openWorld/idempotent hints.

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 exceptionally dense; every sentence carries operational value such as auth constraints, alternatives, output semantics, depth behavior, or timing. It is front-loaded with the most critical constraint (account required) before diving into mechanics.

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

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

For a tool with no output schema, the description fully compensates: it defines what is returned, the shape of each finding, when gaps/contradictions appear, how citations are stabilized, and expected runtime. It also routes to the correct sibling tools for unsupported cases, making the definition self-sufficient.

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?

Even though schema coverage is 100%, the description adds substantial meaning: depth:'quick'/'standard'/'thorough' behaviors are explained in terms of facets, hops, gap recovery, contradiction scans, and paid access. It clarifies that 'question' should be natural language and broad/multi-part is acceptable.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in ONE call. It explicitly differentiates from siblings by saying 'this is NOT open-web search' and calling out ask_pipeworx as the alternative for single 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?

Usage guidance is explicit: it tells agents to use ask_pipeworx when not signed in, for single lookups, and for breaking/colloquial current-news topics. It also gives concrete example queries that fit deep_research, such as 'compare X and Y's regulatory + financial exposure'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by detailing what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' 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 front-loaded with the core purpose and includes actionable usage guidance. The long list of data categories is useful for scoping the tool's coverage, though the list of synonyms ('browse, search, look up, or discover') is slightly redundant. Overall, it is appropriately sized for a discovery 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?

The description is complete for a discovery tool with no output schema. It explains what it returns (top-N relevant tools, names, descriptions, full input schemas, curated examples), states that results are directly callable, and provides clear 'when to use' guidance. The schema covers all parameters, and the description fills the return-value gap adequately.

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 does not add much beyond the schema for parameters; it only reinforces the query concept ('describing the data or task'). The schema itself already documents the 'query' field and its aliases with examples, so the description adds marginal value.

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

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

The description clearly states a specific verb and resource: 'Find tools by describing the data or task,' and further elaborates with concrete domains (SEC filings, financials, FDA drugs, etc.). It distinguishes itself from sibling tools by emphasizing 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist for...' and prescribes 'Call this FIRST...' when many tools are available. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough to guide an agent.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the fan-out source list, GDELT→GNews fallback, USPTO API sunset soft-fail behavior, FDA empty-section expectations, resolved_from/resolved_to behavior, and sources_used/sources_failed semantics. This is exceptionally transparent about edge cases and response conventions.

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 by the tool's multi-source complexity and the need to explain expected empty/soft-fail behavior. It is front-loaded with use-case examples and then organized by sources and return fields; minor redundancy with the schema parameter text keeps it from a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return shape. It succeeds by enumerating every returned field, source, fallback, failure mode, and the private-company case. An agent has enough context to invoke this correctly and interpret unusual results.

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 schema already explains ticker/CIK/name values and the interchangeable type field. The description repeats these details and adds some behavioral context like private-company resolution, but it does not materially add parameter semantics beyond the schema.

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

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

States a specific action and resource: 'full cross-source profile of a US public company' in one parallel call. The trigger-phrase examples ('Tell me about X', 'company profile for Microsoft') make the intended query type unmistakable and distinguish it from targeted single-source 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent what to expect for private companies and notes that empty sections are expected, not failures, giving clear selection and interpretation guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds context about clearing sensitive data and that memories were previously saved by the agent, but doesn't disclose additional behaviors like return values or error handling.

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 verb and object, no filler. The pairing note and usage conditions are concise and relevant.

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

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

For a single-parameter destructive operation with idempotent annotation, the description covers purpose, trigger conditions, and relationship to related tools. It is complete for the tool's complexity even without an output schema.

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

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

The input schema covers 100% of the parameter with a description ('Memory key to delete'). The tool description simply says 'by key,' which adds no new semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' identifying the specific action and resource. It distinguishes itself from sibling tools like remember and recall by naming them as companions, implying its complementary role as the deletion operation.

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: stale context, completed tasks, or clearing sensitive data. It also mentions pairing with remember and recall, but does not explicitly state when not to use it or name alternatives beyond these collaborators.

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 value by disclosing that it fetches the page, extracts specific elements, and emits a markdown blob, which are behavioral traits not covered by the annotations. It doesn't mention error handling or edge cases, but given the strong annotation coverage, a 4 is appropriate.

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 core purpose, followed by process details and use cases. It contains no fluff or redundant information, making it concise and well-structured.

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

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

Given the tool's simplicity (2 well-documented params, strong annotations, no output schema), the description adequately covers what the tool does, how it works, and when to use it. The output format is specified ('single text blob'), making this complete for its scope.

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

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

Both parameters (url and max_links) have complete descriptions in the schema, achieving 100% coverage. The tool description adds little new meaning about parameters—it mostly restates what the schema already says (e.g., 'any URL'). With high schema coverage, the baseline is 3, and the description does not elevate it further.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for any URL, and explains the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This specific verb-resource combination distinguishes it from siblings like ai_visibility_check 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 includes a 'Useful for:' section listing three concrete scenarios (client indexing, drafting for own project, competitor auditing), which provides clear context on when to use it. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing that it lists only the caller's subscriptions (scoping) and by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count). 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 concise sentences: the first states the action and return value, the second gives usage guidance. No wasted words, and the most critical information (what it lists) is front-loaded.

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

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

For a simple list tool with no output schema and minimal parameters, the description is complete. It explains what is returned, that it is scoped to the caller, and why you would use it (review monitoring or find id to cancel). No significant 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?

Schema coverage is 100% with the include_inactive parameter already having a clear description in the schema. The tool description does not repeat or add extra meaning to the parameter, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'List' and identifies the exact resource: 'the caller's active subscriptions'. It also mentions the return fields, making the purpose unmistakable. While it doesn't explicitly name sibling alternatives, the resource and action clearly differentiate it from subscribe/unsubscribe and other 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?

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and a practical use case, though it does not mention when not to use it or 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 declare readOnlyHint=true and destructiveHint=false, covering safety. However, the description adds no behavioral traits beyond that, such as return behavior, ordering, or limitations. It simply states purpose, which is already evident from the name and schema.

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 at five words, with no wasted language. It front-loads the core concept, though it may be too terse to serve as a strong standalone 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?

With a rich schema (100% param coverage), output schema, and annotations, the description can be minimal. However, it lacks usage context, examples, or any differentiation from siblings, making it only minimally complete for safe 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?

The input schema describes both parameters with 100% coverage ('Source Reactome event id' and 'Target species'). The description does not add extra semantic meaning beyond the schema, but the schema itself is sufficient, so a baseline of 3 is appropriate.

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

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

The description 'Orthologous pathways/reactions in another species' clearly indicates the resource (orthologous pathways) but lacks an explicit verb like 'get' or 'find'. It distinguishes from siblings like 'pathway' by mentioning 'in another species', but the noun-phrase construction leaves the action implied.

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?

No guidance is provided on when to use this tool versus alternatives. The sibling list contains related tools like 'pathway' and 'pathways_for_entity', but the description gives no context for choosing 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no behavioral context beyond the annotations, such as output format, rate limits, or any special behavior. No contradiction, but no added transparency.

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

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

The description is extremely short, but this is under-specification rather than conciseness. It is a fragment with no sentence structure or useful information, providing no value despite its brevity.

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

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

Although an output schema exists, the description does not leverage it. With one required parameter and a vague purpose, the description is far from complete for an agent to invoke the tool correctly. It fails to explain what the tool returns or how the input relates to the output.

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 0% schema description coverage, the description must compensate for the 'id' parameter, but it does not. It is unclear whether 'id' refers to a pathway ID, participant ID, or entity ID. The description gives no hint about what value to pass or how it is used.

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 'Entity participants of a pathway' is a noun phrase without a verb, making it unclear what action the tool performs. It vaguely hints at retrieving participants but does not specify whether it lists, gets, or resolves them, and it does not distinguish from sibling tools like 'pathway' or 'pathways_for_entity'.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or any exclusions. Given the sibling tools, there is no indication how 'participants' fits into the broader toolset.

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 the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds context about the stable id requirement and the 'full' nature of the record, which is useful. However, it does not disclose rate limits, error behavior, or the structure of the returned data beyond what the output schema presumably provides.

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, directly stated sentence that is front-loaded and free of any redundant information. Given the simplicity of the tool (one parameter), it is appropriately sized and every word earns its place.

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

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

The tool has one parameter, an output schema, and comprehensive annotations. The description sufficiently explains the input and the nature of the response ('full pathway record') for a simple lookup. It could mention potential failure modes or the specific domain of the stable id (Reactome), but with the output schema and annotations present, the description is largely 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 input schema provides only a parameter name and type with no description, and the schema description coverage is 0%. The description compensates by clarifying that the 'id' is a stable pathway identifier and gives a concrete example (R-HSA-68886). This significantly aids the agent in understanding what value to supply, even though it could offer more detail about the id format or source.

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

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

The description clearly states that the tool retrieves a full pathway record using a stable identifier, with a concrete example. It distinguishes itself from sibling tools like 'pathways_for_entity' by emphasizing the full record for a single pathway. However, it lacks an explicit verb (e.g., 'Get' or 'Return'), which prevents a perfect score.

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

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

No explicit guidance is given on when to use this tool versus the many sibling tools such as 'pathways_for_entity' or 'entity_profile'. The phrase 'by stable id' implies usage when the agent has a stable identifier, but there is no mention of alternatives, exclusions, or specific scenarios. This is essentially no guidance beyond the basic description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond what the schema provides (e.g., citing external resource id). With annotations covering the safety profile, the description meets the baseline but does not enrich transparency with details like return variability or pagination.

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

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

The description is a single, front-loaded sentence: 'Pathways containing an entity, looked up by external resource id (e.g. UniProt accession).' Every word earns its place, no redundancy or filler.

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

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

The tool is a simple read-only lookup. It has a rich input schema, annotations for safety, and an output schema. The description, while brief, tells the agent what it does and the input style. It is sufficiently complete for this complexity level, though it could mention that multiple pathways may be returned, but the openWorldHint and output 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?

Input schema has 100% coverage: all three parameters (species, resource, entity_id) are described with defaults and examples. The description only reinforces the entity_id example (UniProt accession), adding no extra semantic 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 states the tool finds pathways containing an entity via external resource id, with a concrete example (UniProt accession). This clearly differentiates it from siblings like 'pathway' (which likely fetches a specific pathway) and 'participants' (which lists entities in a pathway). The verb 'containing' and resource scope are specific.

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

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

The description implies usage context: use this when you have an external resource identifier and need to find associated pathways. It does not explicitly state when not to use or mention alternatives, but the context is clear enough for a simple lookup 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 description adds substantial behavioral context beyond the empty annotations: rate-limiting ('5 per identifier per day'), free usage ('doesn't count against your tool-call quota'), the claim_token workflow for tracking fixes, and the team's daily digest process. It also instructs against pasting user prompts, clarifying expected input format. No contradiction with annotations.

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

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

The description is a single dense paragraph, but every sentence carries essential guidance. While longer than the ideal 2-3 sentences, the content justifies the length due to the tool's nuanced scope, token handling, and rate limits. No redundant filler.

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

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

For a feedback-routing tool with no output schema, the description covers all necessary context: purpose, applicable scenarios, exclusions, format expectations, token-based follow-up, rate limits, and quota impact. It fully equips the agent to decide when and how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the claim_token parameter by explaining the workflow ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), adding meaning beyond the schema's simple description. Other parameters are already well-documented in the schema.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from sibling tools by focusing on submitting feedback about Pipeworx tools rather than querying data or 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?

Explicit usage criteria are provided: '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 also gives a clear exclusion for non-Pipeworx tools and directs the agent to file with the appropriate server, including a fallback 'Not sure?' check.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses behavioral traits: self-aggregating, derived from CF analytics-engine, no PII, caching behavior (5min-1h), and output structure (pack, tool, count). This adds valuable context not present in 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?

The description is front-loaded with a clear opening sentence, followed by a well-structured list of use cases and a final note on data characteristics. It is slightly verbose but every sentence contributes useful information, earning a strong 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?

For a read-only tool with one optional parameter and no output schema, the description is thorough: it clarifies what is returned, why it is useful, how data is sourced, and its freshness. No important aspect is left unaddressed.

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

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

Schema description coverage is 100%, with the window parameter fully explained in the schema (enum values and tradeoffs between windows). The description only briefly mentions the window in passing without adding any new semantics, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool returns trending data ('top tools, top packs, and total call volume') from 'other AI agents' calling on Pipeworx. It distinguishes from sibling tools like ask_pipeworx (question answering) and discover_tools (discovery) by focusing on aggregated call trends.

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 'Useful for' section explicitly lists three concrete scenarios (discovering hot data sources, confirming canonical tool, checking alignment). It provides clear context but does not explicitly mention when not to use it or name alternative tools, keeping it slightly below the highest tier.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds rich behavioral context: partition filters, placeholder check, fill check with realizable edge explanation, and a direct warning 'do not trade it' when the edge is not realizable. This far exceeds the baseline.

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

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

Though long, the description is meticulously structured: leading summary, then mode-by-mode breakdown, with bolded section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) improving scannability. Each sentence contributes distinct information—no filler or repetition.

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

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

Given no output schema and complexity, the description fully compensates by describing response shapes (opportunities[], partition_check{}), edge cases, and recommended actions. It also contextualizes the tool among siblings and covers failure/skip conditions, making it self-sufficient for an agent.

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

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

Schema coverage is 100% with meaningful property descriptions, but the tool description goes well beyond: it gives concrete examples (e.g., 'fed-decision-may-2026'), explains what each mode does with those parameters, and describes the no-arg behavior. This adds substantial semantic depth.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool from siblings by detailing its three modes (no-args, event, topic) and relation to other Polymarket tools.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event... or topic'. It even recommends event mode for specific markets, explains cross-event advantages, and points to 'polymarket_fill_risk' for custom sizing, setting clear boundaries with alternatives.

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

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

The description adds substantial behavioral context beyond the annotations: caching at KV level for 1 hour, edge computed net of slippage, Kelly caps at 0.25, Fed bet exclusion rationale, diagnostic funnel counters, and knob behavior. It aligns with the readOnly/idempotent annotations and provides rich detail about internal mechanics.

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

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

The description is very long and dense, covering model family details, edge calculations, knobs, and response structure. It front-loads the core purpose well, but the extensive detail makes it less concise than ideal. While every detail has informational value, the length may overwhelm agents that need quick comprehension.

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

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

With no output schema, the description carries the full burden of explaining the return structure. It does this thoroughly: top-level by_segment keys, per-opportunity fields like edge_pp_net and kelly_fraction, diagnostics with funnel counters, and reasons for empty segments. This is comprehensive for a complex tool with 9 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%, so each parameter has a detailed description. The tool description mentions the tradeable-edge knobs (min_liquidity, max_spread_pp) and min_partition_leg_kelly, but these are already explained in the schema. The description does not add significant semantic value beyond the schema, though it does reinforce the relationship between knobs and filter behavior.

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 function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It names the three response segments and three model families, effectively distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It indicates the intended context and gives details on filters and exclusions, but does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: 60-day snapshot TTL, snapshot gaps when no scan occurred, decay computed from daily closes (not intraday), and the response structure including expired opportunities. This is rich, non-obvious information that helps the agent anticipate behavior.

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

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

The description is long but well-structured, starting with a clear purpose, then args/response/limits. Every sentence earns its place, though the 'Args:' section somewhat duplicates schema information. Slightly verbose 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?

No output schema exists, so the description compensates by thoroughly explaining return fields (tracked[], expired[], snapshot_dates[]), their semantics, and edge cases (snapshot gaps, TTL limits). It also clarifies that decay is computed from daily closes. This is complete for a complex telemetry 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 descriptions for both params: days (lookback, default 14, clamp 2-30) and window (24hr | 1wk | 1mo, default 1wk). The description restates these defaults and adds the 'snapshot family' context, but adds no additional value beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges by focusing on time-series tracking rather than raw edges, and differentiates fresh vs old edges.

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

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

The description provides clear context for when to use the tool: when you need to know edge persistence and decay. It explains the significance ('a fresh wide edge and a 3-week-old wide edge are different trades') and mentions the source (polymarket_edges snapshots). It doesn't explicitly name alternatives or exclusions, but the context strongly implies appropriate use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description reinforces this without contradicting it. It adds significant behavioral detail beyond annotations: walks the order book ladder, returns specific fields like slippage_pp and max_fillable_usd, and discloses partial-fill risks and forced_directional_risk naming legs that could strand the user unhedged.

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 long, dense paragraph but every clause carries functional information. It is front-loaded with the purpose and required parameter, then details modes and outputs. A bit more structure (e.g., sections for single-market vs basket) would improve scannability, but it's not padded.

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

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

For a complex tool with two modes, no output schema, and no required parameters, the description is exceptionally complete: it covers both modes, key return fields, default behaviors, edge risks, and the exact usage threshold. It also explains the dominant loss mode (partial basket fills) which gives the agent actionable context for when to invoke this tool.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains how size_usd is interpreted differently in single-market vs basket mode, how 'side' defaults in basket mode based on partition sum, and that market/event modes are mutually exclusive. This is far beyond what the schema provides.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by framing it as a pre-trade risk check rather than a signal finder.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk rationale (theoretical overround not capturable on thin books, partial fills convert arb into unhedged position), giving clear when-to-use 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 and idempotentHint, and the description adds substantial behavioral disclosure beyond those: spread values are gross not net, Kalshi fees are not modeled, compatibility codes can be non-empty even when pairs are returned, pairing is keyword-based and unverified, unclassified legs are never paired, and null temporal alignment means unknown not aligned. This is far beyond what annotations alone convey.

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

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

The description is long, but it is densely informative and well-structured with CAPS-labeled sections for modes, response shape, safety fields, codes, fees, and skipped counters. The purpose is front-loaded in the first sentence. A few clauses could be tighter, but the complexity of the tool justifies most of the length.

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

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

There is no output schema, so the description fully carries the burden of explaining the response: leg-by-leg prices, top_spreads_pp, compatibility_warning, compatibility_codes, temporal_alignment, skipped counters, and fees_note. It also covers all three optional parameters, the behavior when both modes are used, and important caveats. Nothing essential for calling the tool correctly 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%, so the baseline is 3, but the description adds meaningful extra semantics: both modes run the same token-overlap matcher and the same disclosures apply, topic is a fixed list of macro shortcuts, and explicit ticker/slug override the topic-mapped sides. This enriches the bare parameter descriptions without redundancy.

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 statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also explains the two invocation modes and what the matcher does. However, it does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so the differentiation is implicit rather than stated.

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

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

The description gives clear context for choosing between the two modes: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug. It also cautions that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly say when to prefer this tool over sibling alternatives, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and safe behavior. The description adds valuable context about the tool's scope ('Scoped to your identifier') and the two operational modes (retrieve vs. list all). This goes beyond the annotations without contradicting them, though it does not detail return format or error conditions.

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

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

Four concise sentences cover purpose, usage, scoping, and pairing with siblings. Each sentence delivers new information without redundancy. The examples are helpful, though the description could be slightly tighter without losing clarity.

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

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

For a simple tool with one optional parameter and strong annotations, the description is sufficiently complete. It explains the two output behaviors, usage context, and data isolation. It does not describe the return format, but given the simplicity and presence of annotations, this is a minor gap.

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

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

Schema coverage is 100%, so parameters are fully documented there. The description adds meaningful semantics by explaining that omitting the key triggers listing behavior and that the key refers to a previously saved memory. This enriches the schema's simple 'key' 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 two modes: retrieving a saved value and listing all keys. It explicitly names the related operations ('remember' and 'forget'), distinguishing it from siblings. The verb 'retrieve' and resource 'saved memory keys/values' make the purpose unambiguous.

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

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

Provides explicit when-to-use context: 'Use to look up context the agent stored earlier' with concrete examples. It also implicitly states when not to use it by mentioning alternatives ('Pair with remember to save, forget to delete'). This clearly directs the agent to the correct sibling for write/delete 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?

The annotation readOnlyHint=true is contradicted by the description's explicit statement that setting mark_read:true flags returned events as read, modifying state. This is a direct contradiction. No other behavioral context compensates for this inconsistency.

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 compact paragraph. It front-loads the purpose, then concisely covers return contents, filtering, mark_read behavior, and polling suitability. Every sentence adds meaningful information without redundancy.

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

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

For a tool with 5 optional parameters and no output schema, the description covers return payload contents, filtering options, mark_read semantics, polling safety, and an alternative access URL. It lacks exhaustive edge-case details but is largely complete for practical use.

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 all parameters are documented. The description adds value by giving a concrete example for the type parameter (sec_8k) and explaining the cross-call effect of mark_read (next call only shows newer ones), which is not solely apparent from 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 pulls fired events from the subscription feed, using a specific verb and resource. It distinguishes from siblings like list_subscriptions by focusing on alert retrieval, and the mention of evaluator-written alerts adds specificity.

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: it is for retrieving recent alerts and is suitable for polling. It also mentions an alternative endpoint for scripts, but does not explicitly exclude other sibling tools or state 'use this instead of X'. Still, the intended usage is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description goes well beyond by disclosing fan-out to multiple external APIs in parallel, the GDELT→GNews fallback, USPTO's soft-fail due to PatentsView sunset, and the return structure (changes[] grouped by source, total_changes, citation URIs). 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 dense but well-structured: it starts with recognition patterns, defines the core behavior, enumerates sources with fallback details, and ends with the alternative tool. Every sentence contributes useful context without redundancy or padding.

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

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

Even without an output schema, the description covers the return format (structured changes[], total_changes, pipeworx:// citation URIs), source-level behavior, fallbacks, and parameter handling. It also positions the tool against entity_profile, making its scope fully understandable for an agent.

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

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

Schema description coverage is 100% — the schema already documents type, since, and value with format examples. The description repeats the `since` format and entity types but adds no new parameter-level meaning. Per the rubric, a high-coverage schema means a 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 natural-language queries and then explicitly states it's a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' listing sources (SEC EDGAR, GDELT/GNews, USPTO). It clearly distinguishes itself from the sibling entity_profile by contrasting the dynamic feed with the static 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?

It provides concrete example phrasings for when to use the tool ('What's new with X' / 'latest on Y'), and explicitly directs users to 'Use entity_profile instead when you want the static profile...' It also describes fallback behavior (GDELT preferred, GNews on rate-limit/5xx), which informs usage decisions.

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 meaningful behavioral context beyond the annotations: memory is scoped by identifier, and persistence differs for authenticated vs anonymous sessions (permanent vs 24 hours). Annotations only indicate idempotence and non-destructiveness, so this extra context raises the score. It doesn't mention overwrite behavior, but the idempotentHint already implies safe repeated calls.

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 core purpose, followed by usage context and persistence details. Every sentence earns its place—no redundant filler—and it is well-structured for quick scanning.

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

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

For a simple key-value store tool with two well-documented parameters, no output schema, and clear annotations, the description covers purpose, usage scenarios, persistence behavior, and related tools. It is complete enough for an agent to select and invoke the tool correctly without ambiguity.

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

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

The schema already documents both parameters (key and value) with examples and full coverage, so the description's additional mention of 'key-value pair' adds little semantic value. The description's note about scoping by identifier is more about the storage context than the parameters themselves, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes from siblings by giving examples (ticker, address, preference) and explicitly pairing with recall/forget, which are retrieval and deletion tools respectively.

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 usage guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names the related tools (recall, forget) to indicate complementary alternatives, making it clear when to use this tool versus the siblings.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses graceful degradation when GLEIF/OpenFIGI is unavailable, internal cascading through multiple lookup endpoints, explicit `unresolved` reporting instead of silent omission, and ambiguous-match behavior returning `figi_candidates`. This is rich behavioral context the annotations alone do not provide.

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

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

The description is front-loaded with common user phrasings and a clear directive, and every clause carries useful information. It is long and dense, with large parentheticals, but the complexity of the tool justifies most of the length; a little more structuring would make it easier to scan.

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

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

Given the tool's complexity, two entity types, and multiple backing sources, the description covers edge cases such as ambiguous bonds, non-US issuers, unresolved identifiers, and degraded enrichment. Even without an output schema, it tells the agent what to expect in ambiguous and failure cases, making it complete enough to invoke correctly.

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

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

Although the schema already describes both parameters, the description adds critical semantic guidance: accepted input formats like ticker versus CIK versus ISIN, brand versus generic drug names, and a concrete warning to pass only the entity name for bonds, with an example showing why trailing security-class words fail. This materially improves correct invocation.

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

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

The description states a specific verb and resource: resolve a user-spoken name to the canonical/official identifiers other tools require. It also distinguishes itself from siblings by positioning it as the first step whenever a name needs to become an ID, and by listing the two supported entity types with their exact identifier outputs.

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 usage direction with 'Use FIRST whenever you have a name but need an ID' and explains what inputs it accepts. It does not explicitly name alternative tools to avoid, but the clear context and priority instruction are strong enough for an agent to select it correctly.

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 meaningful behavioral context beyond the annotations: it discloses that the tool 'Probes each entity ... with ai_visibility_check, ranks by score', and specifies the output as 'ranked list with score, confidence, signal density per entity'. It also notes that the first entity is treated as the 'subject', which is a non-obvious behavior. Annotations already declare readOnly/idempotent, so the bar is lower; this extra detail earns a 4.

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 primary action, then mechanism and use case. Every sentence contributes: it states what it does, how it does it, and when to use it. There is no redundant filler or repetition of schema details.

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

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

The tool is moderately complex (4 params, no output schema), but the description compensates by summarizing the return format ('ranked list with score, confidence, signal density per entity') and the procedural behavior. It also hints at the dependency on ai_visibility_check. Without an output schema, this description is nearly sufficient for an agent to anticipate what the tool will return. A minor gap is lack of detail on error conditions or model selection behavior, but overall it is 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%, and the description itself does not add parameter-level details beyond what the schema provides. The schema already documents that entities is an array of 2-8 with the first as subject, and explains models, _apiKey, and context. Per the baseline rule, when schema covers parameters fully, a score of 3 is appropriate.

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

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

The description starts with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the probing mechanism (ai_visibility_check) and the ranking output. The competitive audit use case is explicit, making the tool's purpose unambiguous.

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

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

The description provides a clear context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' This tells the agent when to use the tool, but it does not explicitly state when not to use it or mention alternatives. It lacks the 'when-not' guidance that would earn a 5, but the context is sufficiently clear.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds valuable context beyond annotations: partial failures degrade gracefully, the bundlephobia first measurement can take 5-30s, and the sources_failed field lists timeouts. This clarifies expected runtime behavior and failure handling, which is especially useful for an agent deciding whether to invoke the tool.

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 for its content: each sentence adds distinct value—purpose, when to use, return structure, ecosystem scope, and failure mode. It is well-structured with a clear opener and logical flow, and avoids redundant fluff or repetition of schema details.

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

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

Despite having no output schema, the description fully enumerates the return fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, timeout behavior, and partial failure, making it sufficient for an agent to decide on invocation and interpret results.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully. The description does not add new parameter-level details beyond what the schema provides (e.g., version defaults to latest, scoped packages accepted are already in the schema). It provides context in the overall narrative but not additional syntax or format specifics, so the baseline score of 3 applies.

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

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

The description opens with a specific, actionable definition: "Composite 'should I add this npm package to my project' check in ONE call." It clearly identifies the resource (npm package) and the main action (checking licenses, advisories, bundle size, etc.), and distinguishes it from any sibling tool by its unique composite nature across deps.dev and bundlephobia.

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

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

The description explicitly states when to use: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also provides a clear exclusion for non-NPM ecosystems ("PyPI / Maven / Cargo / Go fall under deps.dev:version directly"), serving as an alternative for those cases. It stops short of naming a specific sibling tool but gives actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds behavioral detail about the return format: 'returns stable IDs and display names grouped by type', and indicates the scope ('across all object types'). This goes beyond the annotations and gives the agent useful expectations about output structure.

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, tightly written sentence that front-loads the primary action and resource, then efficiently specifies scope and output. Every clause contributes, with no filler or redundancy.

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

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

The tool is relatively simple (3 parameters, one required) and a structured output schema exists, so the description need not explain return values. The description covers the search scope, object types, and output grouping, which is sufficient for an agent to select and invoke the tool correctly. The available annotations further complete the picture.

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

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

The input schema covers the 'types' and 'cluster' parameters with descriptions, but 'query' is undocumented. The description compensates by identifying 'query' as a keyword, and the enum examples (Pathway, Reaction, Protein, Complex) clarify valid 'types' values. This adds meaning beyond the schema, though not exhaustive.

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

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

The description clearly states the tool's purpose: 'Search the Reactome biological pathway database by keyword across all object types'. It uses a specific verb ('Search') and resource ('Reactome biological pathway database'), lists example object types, and specifies the output ('returns stable IDs and display names grouped by type'). This unambiguously distinguishes it from a generic search tool.

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

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

The description conveys clear usage context: it is a broad keyword search spanning all object types, making it appropriate as an initial discovery step. It does not explicitly mention alternatives or exclusions, but the phrase 'across all object types' implies a general-purpose search, and sibling tools like 'search_within' are implicitly different. This meets the 'clear context, no exclusions' level.

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?

Given annotations already state readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds significant behavioral detail: character offsets, similarity scores, BGE-base-en embeddings, cosine over 500-char overlapping windows, and a 200K char cap with truncation flagging. This goes well beyond the annotations and gives the agent concrete expectations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose and then packs each sentence with useful details: return format, use case, pairing, embedding algorithm, and limits. No sentence is wasted, and the length is appropriate for the tool's complexity.

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

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

The tool has no output schema, but the description covers what the agent will receive (top-N passages with offsets and similarity scores). It also discloses truncation behavior, algorithm choice, and workflow pairing, making it fully self-contained for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical examples for text (SEC 10-K body, article, long tool result) and for query (supply-chain risk, fiscal year revenue), plus clarifies that text is something already pulled. This enriches the parameter understanding beyond the 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 opens with 'Semantic search INSIDE a fetched record,' giving a specific verb, resource, and scope. It clearly distinguishes from siblings like search by emphasizing the input is already-fetched text, and it references ask_pipeworx_grounded as a complementary tool.

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context and returning only relevant passages. It also pairs with ask_pipeworx_grounded to show the intended workflow, though it does not explicitly list exclusions 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?

Despite annotations already covering idempotency, non-readonly, and non-destructive behavior, the description adds meaningful context: authentication requirements, an always-on feed, optional email/sms delivery, phone verification, and daily SMS caps. It does not contradict annotations, though it omits webhook details that are covered in the schema.

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 core purpose, followed by prerequisites, supported types, and delivery channels. It is dense but not excessively long; some redundancy with the schema (e.g., SMS cap and type examples) makes it slightly less concise than ideal.

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

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

The description covers the return value, auth requirements, subscription types, and delivery options, and is complemented by a rich input schema that details all parameters. The absence of an output schema is mitigated by stating the return value, but the description alone does not explicitly mention webhook behavior, though the schema does.

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 already contains detailed type-specific parameter examples and delivery constraints. The description re-iterates examples and adds small semantics like 'items:["5.02"] = officer change,' but largely duplicates the schema, so it does not substantially elevate understanding beyond the structured definition.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream,' and states the return value. It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by being the creation operation.

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

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

The description provides clear context on when to use the tool—for ongoing proactive monitoring of live events—and lists supported subscription types with examples. It also notes a prerequisite (Pipeworx OAuth account), but does not explicitly describe when to prefer alternative tools for one-off queries or exclusions.

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

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

Annotations already flag readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool and argument shapes from the live catalog, and explains how the 'topic' parameter affects the response. It doesn't mention performance or rate limits, but given annotations cover safety, this is sufficient.

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 comprehensive sentence that front-loads example queries and conveys the purpose, return value, and usage. It is efficient and every clause contributes meaningful information. While not as tightly structured as a two-sentence summary, it avoids fluff and is appropriately sized for the tool's scope.

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-only tool with no output schema, the description is fully complete. It explains what the tool returns (category-bucketed questions with tool+argument shape), when to use it, how to invoke it with or without the topic parameter, and its role relative to meta-tools. The agent has all necessary information to select and call this tool correctly.

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

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

The input schema has 100% coverage with a description for the single 'topic' parameter. The description enriches this by clarifying that omitting the parameter returns a full spread, while passing a topic focuses the results. It also provides concrete examples ('finance', 'pharma', 'betting'), which the schema lacks. This goes beyond simple restatement.

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

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

The description clearly identifies the tool as an onboarding entry point for an agent to discover what questions it can ask Pipeworx. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes it from siblings by positioning it as the 'FIRST' tool to use when unfamiliar with Pipeworx, unlike discover_tools or ask_pipeworx.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides clear guidance on when to pass the optional 'topic' parameter versus omitting it, and gives examples. This effectively tells the agent when to use this tool and the 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?

The description discloses that ownership is enforced and that the row is deactivated rather than deleted, preserving history. This goes beyond the idempotentHint and destructiveHint annotations, adding meaningful behavioral context that an agent needs to know.

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

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

Two concise sentences, front-loaded with the primary action, followed by essential behavioral details. No redundant information and 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 single-parameter mutation tool with no output schema, the description covers the action, ownership constraint, and the non-deletion effect. This is sufficient for an agent to understand the tool's behavior and select it correctly.

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

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

The schema already documents the single 'id' parameter as the subscription uuid returned by subscribe (100% coverage). The description adds 'your own subscriptions' context but doesn't provide additional syntax or format details, so the schema carries the heavy lifting.

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

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

The description uses the specific verb 'Cancel' with the resource 'subscription', clearly differentiating from sibling tools like 'subscribe' and 'list_subscriptions'. It states exactly what the tool does and its 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?

The description states the action and the ownership constraint, implying when to use it (to cancel your own subscription). It doesn't explicitly name alternatives or exclusions, but the sibling context and 'recent_alerts' mention provide clear context for appropriate usage.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral nuances: the verdict types, the special meaning of 'could_not_verify' (indicating a failure to check, not evidence), and 'unsupported' (no source found). It also warns callers not to present 'could_not_verify' as evidence, which is essential for correct invocation and interpretation.

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 well-structured: it starts with example phrases, states the core behavior, explains routing, lists verdicts, and ends with a critical warning. Every section earns its place, though some redundancy exists (e.g., the phrase 'verified via...' could be trimmed). Overall, it is appropriately sized for the tool's complexity.

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

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

Given that there is no output schema, the description thoroughly covers return values (verdict, value, citation, reasoning) and explains the semantics of each verdict. It also details the two processing paths and the fallback behavior. This ensures an agent can correctly select and invoke the tool without needing additional documentation.

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 provides 100% coverage for both parameters, with detailed descriptions for 'claim' and 'tolerance_pct'. The tool description does not add per-parameter details beyond what the schema offers, but mentions 'exact percent-delta math' and tolerance overriding, which slightly reinforces the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as 'natural-language claim verification against authoritative sources' and provides concrete trigger phrases like 'fact check' and 'verify the claim that…'. It specifies the verb (verify/validate) and resource (factual claims), and the scope is well-defined, distinguishing it from search or entity resolution 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?

Explicit guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for company-financial claims vs other claims. However, it does not name specific sibling tools to avoid or provide explicit when-not-to-use conditions, only implying they are unnecessary because the tool handles all claim types.

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