Pride

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 those: it discloses cost implications ('BYO key — you pay Anthropic directly'), data flow ('Passed straight through to api.anthropic.com'), and the return structure per-model. It does not mention rate limits or failure modes, but the annotation coverage lowers the bar and the description adds meaningful context, so 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 two sentences, well-organized and front-loaded. The first sentence explains the core function and default behavior; the second covers output and use cases. Every word earns its place, with no redundancy or filler. It is compact yet information-dense.

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

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

For a read-only, moderately complex tool with 4 params and no output schema, the description is complete. It explains what the tool does, default behavior, optional API key, return format, and use cases. Annotations cover safety and the schema covers param details, so there are no critical gaps. The description is sufficient for an agent to decide when and how to use 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 description coverage is 100%, so the baseline is 3. The description enhances parameter understanding by explaining the default model ('Default model is Workers AI Llama-3.3-70b (free)') and that omitting models uses just workers-ai. It also clarifies _apiKey is only needed if 'anthropic' is in models and that it is passed directly. These details go beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know... and score visibility (0-100) per model.' It uses a specific verb ('probe') and a distinct resource (LLMs), which differentiates it from sibling tools like ask_pipeworx or scan_competitor_ai_presence. It also specifies the output format and default model, making the purpose unmistakable.

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

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

The description provides clear use cases: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also clarifies when to pass _apiKey and that the default model is free. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it falls short of a 5 by not offering 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 declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns pipeworx:// citation URIs, and notes 'works on every tier, one fast call'. This enriches the annotation data without contradicting it.

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 typical but every sentence adds value: purpose, routing behavior, usage triggers, examples, alternatives, and notes for the default tool. It is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and maintains structure, though it could be tightened slightly.

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 (5,529 tools, 1455 sources) and lack of an output schema, the description is remarkably complete. It explains the routing mechanism, citation output, comparison to siblings, and provides a wide range of examples. It leaves little ambiguity about when and how to use 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% and all six parameters are aliases for a single natural-language question. The description goes beyond schema by offering concrete example queries and a trigger-phrase list ('what is', 'look up', 'find', etc.), which helps the agent know what to put in the parameter.

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

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

The description clearly states the tool's purpose: it answers factual questions by routing to thousands of verified sources and returning structured answers with citations. It distinguishes itself from siblings (ask_pipeworx_grounded, deep_research) by positioning itself as the fast default entry point, making its role unambiguous.

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

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

Explicit guidance is given on when to use this tool over alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternative tools named (ask_pipeworx_grounded, deep_research). It also covers breaking-news cases, providing clear when-to-use and when-not-to-use instructions.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description explains the beta status, that candidate routing improvements may be enabled live, that results are compared against stable router for merge decisions, and that it is fully functional rather than a fallback. This adds meaningful context.

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

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

The description is compact and front-loaded, with every sentence adding value: beta status, identical behavior, current state, usage instruction, and reassurance of full functionality. No waste.

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

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

Despite no output schema, the description states the response shape is identical to ask_pipeworx, which covers expectations. It also addresses current state, usage, and experimental context, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100%, and the input schema fully explains the 'question' parameter and its aliases. The description only says 'same arguments as ask_pipeworx,' which provides no additional parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes from siblings by explicitly referencing ask_pipeworx and noting the beta status and experimental edge.

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 to 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router. It also explains that when no candidate is active, it matches ask_pipeworx exactly, giving clear selection criteria.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists five explicit refusal reasons. It also discloses the extra LLM call cost, which is significant beyond the annotations.

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

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

The description is moderately long but well-structured: a lead purpose sentence, then the routing/behavior, then detailed return/refusal formats, then use cases and cost tradeoff. Every sentence contributes information, though a slightly more compact phrasing could improve scannability.

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

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

There is no output schema, and the description compensates by fully describing the success return object and all refusal reasons. It also covers the cost tradeoff, use cases, and relationship to ask_pipeworx, making the tool's behavior complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, as the input schema documents the main `question` field and all aliases with descriptions. The description does not add parameter-level details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains that it routes the same as ask_pipeworx but extracts answers only from tool results. This clearly differentiates it from the sibling ask_pipeworx, and the mention of 'same routing' plus output format gives a specific, distinct purpose.

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

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

It explicitly states 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). It also provides an alternative: 'prefer ask_pipeworx for casual lookups,' making the when-to-use and when-not-to-use very 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?

With annotations already declaring readOnly/oepnWorld/idempotent, the description still adds substantial behavioral context: resolver confidence contract, low-confidence short-circuit behavior, closed-market handling, wide-spread tradeability warnings, news fallback fields, and cancellation-rule risk. This is far beyond what annotations provide and gives agents critical safety context.

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

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

Although lengthy, the description is tightly organized with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Every section covers essential operational or safety information without redundant filler, making the length 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?

With no output schema, the description thoroughly explains return structures (result.market, analysis, evidence), resolver alternatives, parent_event partitions, news fallback, safety statuses, and cancellation rules. It also covers all three input formats and depth/raw behaviors. This is a model of completeness for a complex tool.

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

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

Schema description coverage is 100%, with each parameter already well-documented (e.g., depth enum, include_raw default). The description adds value through examples and fan-out details but does not significantly augment the schema's parameter explanations. Per the rubric, the baseline of 3 applies when the schema carries the burden.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools by focusing on evidence gathering and market-vs-model comparison, with explicit use cases such as 'should I bet on X' and 'is there edge in Z'. This goes far beyond a vague restatement of the title.

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 clearly when to use the tool (for bet research, data lookup, edge evaluation) and gives concrete query examples. However, it does not explicitly name alternative tools or provide exclusion criteria (e.g., 'for pure arbitrage use polymarket_arbitrage'), so it falls short of the full 'when-not/alternatives' credit.

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

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

Annotations already provide readOnly/openWorld/idempotent hints. The description adds significant behavioral context: off-calendar fiscal years handled correctly, results sorted by primary metric, and returns paired data with pipeworx:// citation URIs. It also specifies the exact data sources for each entity type, which is 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 dense but well-structured, using bolded examples and clear sections. Every sentence carries weight: usage triggers, data specifics, sorting behavior, and return format. Despite its length, it avoids redundancy and is easy to scan, making it 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?

For a tool with two parameters and no output schema, the description covers all essential aspects: what it does, which data is fetched for each type, how results are sorted, what citations are included, and the performance benefit. It sufficiently informs an agent about invocation and expected output without unnecessary elaboration.

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 type and values, but the description enriches both. It explains that type='company' pulls SEC EDGAR/XBRL data (revenue, net income, etc.) and type='drug' pulls FAERS/FDA/trial counts, which is far more useful than the schema's simple enum listing. The examples and max/min constraints for values also add practical meaning.

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

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

The description states a specific verb and resource: side-by-side comparison of 2-5 companies or drugs in one parallel call. It clearly distinguishes from sibling tools like entity_profile by emphasizing it's for comparing multiple entities and should be preferred over sequential lookups. The detailed examples of natural language queries further clarify the purpose.

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

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

Explicitly states when to use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentions it replaces 8-15 lookups. It also clarifies the types of things that can be compared (companies by financials, drugs by adverse events/trials), providing clear context for selection versus 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the findings packet structure (verbatim evidence, confidence, source, cited_at, citations), the gap[] behavior, the 'never invented' guarantee, contradiction detection, second-hop iteration differences, and latency expectations. This is substantial behavioral context with no contradictions to 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 dense but every sentence carries unique, non-redundant information (account requirement, data source scope, routing mechanism, output contract, alternatives, timing). The single unsectioned paragraph hurts scannability, but given the tool's complexity, the length is justified and front-loaded with the most critical operational hint (account requirement).

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

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

With no output schema, the description fully explains return values, including findings, gaps[], contradictions[], hop fields, and fetchable citation_uri. It also covers edge cases (missing citations, breaking news gaps), performance expectations, and per-depth behavior, making the description complete for an agent to invoke 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?

The schema already provides 100% coverage for both params, so the description doesn't need to explain basic fields. However, it adds meaning beyond the schema by detailing depth-level consequences: 'standard' re-angles unanswered gaps, 'thorough' adds lead-chasing and is paid, thus mapping enum values to behavioral outcomes. It also clarifies that 'question' can be broad/multi-part.

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 deep_research as a grounded multi-source research tool over structured data, using a specific verb+resource+scope construction ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources'). It explicitly distinguishes itself from sibling ask_pipeworx and open-web search, so an agent can unambiguously tell what it does.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also states best-fit scenarios ('broad/multi-part questions over structured data') and notes account-tier prerequisites, making tool selection criteria concrete.

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, and non-destructive behavior. The description adds valuable context about output: returns top-N tools with full schemas and curated examples, and that results are directly callable without a second lookup. This enriches understanding beyond annotations.

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

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

Three sentences, each serving a distinct purpose: defining the action, specifying when to use it, and describing the output. Front-loaded with the primary verb and resource, no wasted words.

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

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

Despite no output schema, the description comprehensively covers what the tool returns (names, descriptions, schemas, examples), supports top-N/limit behavior, and clarifies that results are immediately usable. This is sufficient for a discovery tool.

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

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

Schema description coverage is 100%, and the schema already explains the query parameter and aliases. The description reinforces natural-language usage with examples and lists domains, but adds minimal semantic value beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates numerous specific domains, making it obvious this is the tool-discovery meta-tool. It distinguishes itself from sibling tools by focusing on browsing/searching the toolset rather than performing a specific task.

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 instruction: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. This tells the agent exactly when to invoke it versus directly calling a specialized 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses substantial behavioral details: parallel fan-out across multiple sources, return structure with counts and URIs, sorting order for fundamentals, patent API sunset soft-fail, and GDELT→GNews fallback. This gives the agent a clear picture of what happens when invoked.

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

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

The description is long, but every sentence delivers actionable information: user query examples, the parallel-call behavior, exact return fields, source fallbacks, and input constraints. There is minor redundancy with the schema (e.g., 'names not supported'), but the density of useful content justifies 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?

With no output schema, the description fully compensates by enumerating every returned field, specifying counts (up to 5 filings), URI format, sorting (period_end DESC), source fallbacks, and the patent soft-fail condition. It also clarifies the input constraint and recommends an alternative tool, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100%—both parameters have descriptions already covering ticker vs. CIK and the 'names not supported' caveat. The description essentially repeats those details without adding extra semantic nuance beyond confirming the pattern. Thus it meets the baseline but does not elevate beyond it.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resources, enumerates exact data fields (cik, recent_filings, fundamentals, patents, news, LEI), and explicitly distinguishes from sibling tools by advising preference over chaining single-pack 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?

It provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent when not to use the tool (if only a name is provided: 'names not supported — use resolve_entity first'), making alternatives clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, which convey the safety profile. The description adds the rationale for deleting (sensitive data, stale context) but doesn't disclose additional behavioral details such as irreversibility or behavior on missing keys. This is adequate given annotation coverage.

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

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

The description is two concise sentences: the first states the core action, the second provides usage guidance and sibling relationships. 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?

For a single-parameter mutation tool with rich annotations, the description is complete. It covers what it does, when to use it, and how it relates to sibling tools. No output schema is needed, so missing return details are not a concern.

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 is fully described (100% coverage) with the 'key' parameter clearly documented as 'Memory key to delete.' The description adds no extra parameter semantics beyond what the schema provides, 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 uses the specific verb 'Delete' and identifies the resource as 'a previously stored memory by key,' clearly distinguishing it from sibling memory tools like remember (store) and recall (retrieve).

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 states explicit usage triggers: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with remember and recall, which provides context, though it doesn't explicitly state when not to use this tool versus an alternative.

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

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

The description goes beyond the annotations by disclosing the internal behavior: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output form ('single text blob'). The annotations already indicate a read-only, idempotent, non-destructive operation, and the description adds value without contradiction.

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

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

The description is four sentences, each adding substantive value: what it does, how it works, what the output is, and when to use it. It is front-loaded with the core purpose and contains 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?

With only two parameters, no output schema, and rich annotations, the description covers all necessary context. It explains the output format, the use cases, and the internal process, making the tool fully understandable for an AI agent deciding whether 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?

The input schema has 100% coverage for both parameters ('url' and 'max_links'), so the schema already explains them fully. The description does not add additional parameter-level semantics, only references 'key links' which aligns with the schema. Baseline 3 is appropriate given the 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 uses a specific verb ('Generate') and resource ('production-ready llms.txt file for any URL'), and clearly explains the process and output format. It also distinguishes itself from siblings by focusing on generating the file rather than scanning or checking AI visibility, which is the theme of several sibling tools.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') and makes it clear when the tool is applicable. However, it doesn't explicitly mention when not to use the tool or name alternative sibling tools, so it's not a full when/when-not/alternatives guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the specific return contents (protocols, organisms, diseases, etc.), providing useful transparency about what the agent will receive. 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?

One well-structured sentence that leads with the core action and then enumerates the returned metadata fields. Every word adds value; no fluff.

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

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

For a simple one-parameter getter with strong annotations, the description covers the return values adequately. It might optionally mention error handling (e.g., not-found behavior), but this isn't critical given the straightforward nature and good schema.

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

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

Schema description coverage is 100%, so the schema already documents the accession parameter fully with an example. The description echoes the same example but adds no new semantic meaning beyond schema.

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

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

The description specifies the exact action (get full metadata), the resource (one PRIDE Archive proteomics project), and the key qualifier (by accession). This distinguishes it from sibling tools like search_projects, which presumably search across projects.

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: use when you have a specific project accession and need complete metadata. It doesn't explicitly name alternatives or exclusions, but the accession-based identity makes the usage context unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is established. The description adds behavioral context by specifying the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and scoping to the caller's subscriptions. This goes beyond the annotations by describing the response structure, which is especially valuable given there is no output 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 two sentences: the first states the function and return fields, the second gives a concrete use case. There is no redundant information, and the most important information 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?

With one optional parameter, no output schema, and clear annotations, the description adequately covers the tool's behavior and return values. It explicitly lists the returned fields, explains the caller-scoped nature, and provides usage context, making it complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100%: the only parameter include_inactive is fully described in the schema. The description does not mention this parameter, but the schema carries the meaning, so the baseline of 3 applies. No additional parameter semantics are needed.

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') with a clear resource ('the caller's active subscriptions') and explicitly distinguishes its purpose from adding or cancelling subscriptions by stating 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly separates it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly states when to use the tool: 'before adding more or to find an id to cancel.' This gives direct contextual guidance and implies that subscribe/unsubscribe are the alternatives for those actions. No exclusions are needed because the usage context is unambiguous.

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

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

The description goes far beyond the sparse annotations (all hints false) by disclosing rate limits (5/day), quota-free nature, the claim_token flow for later retrieval, and the fact that the team reads digests daily. It also explains side effects of filing without an account. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose: purpose, usage, exclusions, claim-token mechanics, rate limits, and roadmap impact. It is front-loaded with the core action and logically organized. No filler or redundant repetition of schema fields.

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 and four params, the description explains the return behavior (claim_token on filing, status/resolution when querying with the token), which is essential. It also covers constraints like rate limits and scope. Given the tool's complexity, the description is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, earning a baseline of 3, but the description adds meaningful guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt' for the message field, and it explains the claim_token usage pattern (pass `pwfb_…` with no other arguments). These are extra semantic constraints not present 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 clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately establishes the tool's scope (feedback about Pipeworx tools) and distinguishes it from all sibling tools, which are research/query utilities. No ambiguity exists.

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

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

Explicitly lists when to use: for bugs, feature requests, data gaps, or praise. It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and tells users to file with a different MCP server otherwise. This is textbook alternative/context guidance.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds self-aggregating derivation from CF analytics-engine, no PII, data shape (pack, tool, count), and cache TTL of 5min-1h. No contradiction; this extra context helps agents trust and interpret results.

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

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

Three concise sentences front-load the core purpose and follow with scannable numbered use cases. No redundant filler; every sentence adds distinct value.

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

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

Despite no output schema, the description states the return payload (top tools, top packs, total call volume) and notes privacy/cache behavior. For a one-optional-parameter tool with strong annotations, this is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema covers window with enum and per-window explanation, so baseline is 3. Description reinforces the window list and adds that cache freshness varies by window, slightly enriching parameter understanding. Therefore 4.

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

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

Description uses specific verb 'Returns' and names the resource (Pipeworx agent-call trends). It distinguishes from sibling discover_tools by focusing on real-time aggregated agent usage rather than static discovery. The three use cases further clarify its unique niche.

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 'Useful for' list with three concrete scenarios (current events discovery, canonical tool confirmation, alignment check). It implies when to use but does not explicitly name alternatives or exclusions, so it earns a 4 rather than 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 indicate readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: the partition filter dropping placeholder slugs, the semantic anchor requiring ≥0.30 Jaccard similarity, the fill check that prices theoretical vs realizable edge, and the condition that realizable_edge_pp ≤ 0 means do not trade. This far exceeds the annotation baseline.

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

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

Though lengthy, the description is densely packed with unique, actionable information. It is front-loaded with the core purpose, then organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence contributes to correct tool usage, with no filler or repetition of schema data.

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 two modes, complex filtering logic, and no output schema, the description is remarkably complete. It details the response structure (opportunities[], partition_check), explains edge cases (thin_legs, placeholders_filtered), and provides decision rules (realizable_edge_pp ≤ 0). The description alone is sufficient for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for both event and topic, and the tool description enriches both: it provides concrete examples (event slugs like 'fed-decision-may-2026'), explains the behavior of each mode (partition_check vs cross-event comparator), and clarifies that no args triggers trending_scan. The description adds significant 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 opens with a clear, specific statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This includes the verb (find), resource (Polymarket arbitrage), and method, distinguishing it from siblings like polymarket_edges. It further elaborates on two distinct modes (event and topic), making its scope 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 gives explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool, polymarket_fill_risk, for custom sizing, and explains when not to trade via fill check. This is exemplary usage direction.

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

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

Even with annotations declaring read-only, idempotent, and non-destructive behavior, the description goes far beyond by disclosing caching ('Cached 1h at the KV level keyed on all knobs'), the 24h-move warning, the deliberate kelly_fraction_half=0 for partition_overround parents, placeholder-slug filtering, and diagnostic output for empty segments. These details give callers critical insight into runtime 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: it front-loads the purpose, then uses clear section headers (model families, knobs, response top-level). Every sentence contributes useful information, and the density is justified by the tool's complexity. It could be tightened slightly, but it avoids redundancy and is organized logically.

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

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

With no output schema, the description fully specifies return values: by_segment structure, fed_candidates/fed_note, _diagnostics counters, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h warning). It also explains why segments may be empty and how knobs affect filtering. For a tool with 9 parameters and three model families, this 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 coverage is 100%, so the baseline is 3, but the description adds meaning: it groups min_liquidity and max_spread_pp as 'TRADEABLE-EDGE KNOBS', explains how min_partition_leg_kelly interacts with partition arbs (where parent kelly is always 0), and clarifies that slippage_pp affects edge_pp_net and Kelly sizing. This enhances parameter understanding beyond the raw 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 ('Scan') and resource ('top Polymarket markets'), and clearly states the unique value: returning opportunities where Pipeworx data disagrees with market price. It distinguishes itself by explaining the three model-family segmentation (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and the 'what should I bet on today' use case, which differentiates it from sibling tools.

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

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

It explicitly states the intended use case ('agents discover opportunities without paging hundreds of markets') and includes operational guidance such as tradeable-edge knobs, the Fed candidates exclusion, and the rarity of concentrated longshots. However, it does not name alternative sibling tools or provide explicit when-not-to-use directions, so it stops short of full discrimination.

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

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

Beyond annotations (readOnly, idempotent), description discloses 60-day TTL limits, snapshot gaps on cache-miss, daily-close basis for decay, signed edge_pp_net semantics, and dual metrics computed on absolute value. No annotation 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?

Structured with ARGS/RESPONSE/LIMITS, front-loaded with purpose; every sentence conveys behavioral or response detail without filler, making the long description justified.

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

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

No output schema, but description fully enumerates response fields (tracked, expired, snapshot_dates), their sub-fields (edge_pp_net time-series, trend, decay_pp_per_day, lifespan_days), and caveats, making tool behavior comprehensively understandable.

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

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

Schema covers both params fully (100% coverage): days default/clamp and window options/default. Description only repeats this info (e.g., 'window (snapshot family, default "1wk")') and adds no further parameter-specific semantics, so baseline 3 applies.

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

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

Description states 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and poses the exact question it answers, distinguishing it from sibling polymarket_edges (current edges) by focusing on historical persistence and decay.

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

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

Provides clear usage context: answers 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old wide edges to illustrate when persistence matters. It implies use with polymarket_edges snapshots but does not explicitly name alternatives or exclusion scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond this: it walks the order book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and critically warns that partial basket fills convert an arb into an unhedged directional position. This directly augments the annotation-only safety profile with practical risk details.

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

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

The description is long but every sentence earns its place. It is logically structured: purpose statement, mode requirements, detailed behavior per mode, return fields, and a final usage directive. It is front-loaded with the core function and ends with an actionable 'USE THIS before...' statement. No redundancies or filler; the length is proportionate to 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 no output schema, the description carries the full burden of explaining return values and risk logic. It does this comprehensively: verdict values, per-leg detail, thin_legs[], max_clean_notional_usd, forced_directional_risk, and the real-world reason for the tool. It also covers both operational modes and edge cases like partial fills. This is a complete and self-contained specification.

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 enriches parameter understanding significantly. It explains that size_usd means 'max spend on buys, target proceeds on sells' in single-market mode, and 'settlement notional — shares per leg' in basket mode. It also clarifies that the side parameter defaults to 'auto' in basket mode based on partition sum. These nuances are not fully captured by 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 performs a 'realizable-vs-theoretical edge check' against live order book depth, and enumerates its two modes (single-market and basket). It explicitly positions itself as a pre-trade risk check relative to sibling tools polymarket_arbitrage and polymarket_edges, making its purpose unambiguous and well-differentiated.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains how to choose between market and event modes, and how side and size_usd behave differently in each mode, giving concrete direction on selection and invocation.

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

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

Annotations already declare this as a safe read operation (readOnlyHint=true, destructiveHint=false). The description goes far beyond by detailing when compatibility_warning triggers, how temporal_alignment affects spread validity, the meaning of skipped_cross_type/subtype counters, and the caveat that 'pre-mapped ≠ tradeable.' This is exactly the kind of behavioral disclosure that helps an agent interpret results correctly.

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 well-structured: it starts with a one-sentence purpose, then uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) to organize dense information. Every sentence contributes unique value, and the warning about pre-mapped topics is important honest context. No fluff 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?

This tool has no output schema and moderately complex behavior, but the description compensates fully. It explains the response fields (leg-by-leg prices, spread.pp), safety fields with two distinct warning scenarios, temporal alignment, and skipped counter types. It also sets accurate expectations about how often the tool returns tradeable signals. Complete for an experienced user.

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

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

The input schema already covers 100% of parameters, each with descriptions. The tool description adds value by explaining the relationship between parameters (e.g., 'Overrides the topic-mapped Kalshi side') and the semantics of the 'topic' parameter as a macro-shortcut auto-fetch mechanism. It does not fully explain the response structure of each parameter, but it enriches understanding of how parameters interact.

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

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

The description opens with a precise statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (cross-venue spread), the specific venues, and the condition (same resolving question). It also distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons rather than intra-venue analysis.

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

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

The description provides clear usage context by explaining two modes: pre-mapped topic shortcuts and explicit ticker/slug pairings. It also includes important when-not-to-use guidance, such as warning that 'compatibility_warning' indicates non-equivalent bet shapes or unrelated events, and that temporal_alignment=false makes spreads meaningless. However, it does not explicitly mention alternative tools to use instead, which prevents a 5.

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

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

Annotations already declare readOnly and idempotent, so the safety profile is covered. The description adds meaningful behavioral context: memory is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID), and omitting key lists all keys. This exceeds the baseline by disclosing non-obvious 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?

Three sentences, front-loaded with the primary purpose, followed by usage context and scoping details. No redundancy or filler; every sentence contributes value.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it covers both invocation modes (with/without key), scoping, and relationships to remember and forget. Annotations cover safety, so no additional disclosure is needed.

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

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

Schema coverage is 100% and the parameter description already explains the key parameter and the omit-to-list-all behavior. The tool description essentially restates this, adding no significant meaning beyond what the schema provides. 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 retrieves a value saved via remember, or lists all saved keys when key is omitted. It uses a specific verb (retrieve) and resource (memory), and distinguishes itself from sibling tools remember and forget.

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

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

Explicitly says to use it to look up context saved earlier without re-deriving it, with concrete examples. Does not mention when not to use it, but clear context is provided. Falls short of a 5 because it lacks explicit exclusions or alternative tool references.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds behavioral context beyond these: it explains the feed is written by the evaluator, describes the returned fields (source, citation_uri, raw payload), and clarifies that mark_read causes future calls to exclude read events. This goes well beyond the annotation flags, giving the agent a clear model of state changes despite being read-only.

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 four sentences, each adding distinct value: the first states the core action, the second describes the output shape, the third covers filtering and mark_read, and the fourth provides an alternative access method. It is front-loaded and free of redundant phrasing.

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 list tool with 5 optional parameters and no output schema, the description covers the primary use case, the behavioral semantics (mark_read), filter options, and even an alternative endpoint. The schema covers parameters and defaults, so the description need not repeat them. It's complete enough for an agent to select and invoke correctly.

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

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

The schema already describes all 5 parameters with 100% coverage, so the baseline is 3. The description adds a concrete type example ('sec_8k') and explains the consequence of mark_read ('the next call only shows newer ones'), which enriches the schema's description. Since the added value is modest but present, a 4 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 ('Pull') and clearly identifies the resource ('fired events from your subscription feed'). It also distinguishes this from siblings by focusing on reading alerts, as opposed to subscribing/unsubscribing (subscribe, unsubscribe) or recent_changes. The mention of the alert payload components further clarifies 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 provides clear usage context: it's for fetching recent alerts from the persisted feed, supports filtering by type and time, and explains mark_read behavior. It also mentions polling and an alternative HTTP endpoint for scripts/dashboards, which gives a clear sense of when to use this tool vs. alternatives. It doesn't explicitly exclude other tools but the context is sufficient.

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

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

Beyond annotations (read-only, idempotent), the description discloses multi-source fan-out behavior, fallback logic (GDELT→GNews when rate-limited or 5xx), USPTO API sunset soft-fail, and output structure (changes[] grouped by source, total_changes, citation URIs). This is substantial behavioral context that helps the agent understand side effects and dependencies.

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

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

The description is dense but well-organized, starting with practical query examples, then the core function, source fallbacks, input syntax, output, and alternative tool. It is longer than usual but every sentence provides necessary context, so it earns a 4 rather than 5 for being slightly packed.

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

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

Given no output schema, the description effectively covers the return format (changes[] grouped by source, total_changes, pipeworx:// citation URIs), input variants, and known failure modes (USPTO sunset). The complexity of multiple data sources and fallbacks is well-documented, making the description sufficient for agent invocation.

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

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

Schema description coverage is 100% and already contains the parameter details for `type`, `since`, and `value`. The tool description largely repeats these (e.g., `since` formats, ticker/CIK values) without adding new meaning or edge-case behavior, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with natural language examples like "What's new with X". It explicitly distinguishes itself from entity_profile, stating that static profiles should use that tool instead, which solidifies purpose differentiation.

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

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

The description provides explicit usage guidance by giving example queries and an explicit alternative: "Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window." This tells the agent exactly when to select this tool versus a sibling, fulfilling the dimension fully.

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?

While annotations already indicate it's a write operation (readOnlyHint=false) and non-destructive, the description adds key context: 'scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'. This goes beyond annotations, though it doesn't explicitly address overwrite behavior (covered by idempotentHint=true).

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 action, then gives usage context, scope, persistence details, and sibling relationships in just four sentences. Every sentence adds distinct value without redundancy.

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

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

For a simple save tool, the description is quite complete: it covers persistence, scope, and complementary tools. A minor gap is the lack of return-value explanation, but for a write operation that is often obvious. The idempotentHint covers overwrite semantics.

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

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

Schema coverage is 100%, with each parameter (key, value) having a clear description. The description's 'key-value pair' phrasing adds no extra semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, using the specific verb 'Save' and identifying the resource (data/items). It also distinguishes itself from siblings by explicitly pairing with 'recall to retrieve later, forget to delete'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. It also names alternatives (recall, forget) and clarifies persistence differences between authenticated and anonymous sessions.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds valuable behavioral details: cascading through multiple lookup endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, and explicit reporting of unresolved identifiers. This gives the agent a clear model of side effects and failure modes.

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

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

The description is long but packed with necessary detail and well-structured with labeled sections and examples. It front-loads the key usage directive and user intents, making it easy to scan for the essential decision.

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 adequately explains what will be returned for both entity types, including identifiers, sources, citations, and unresolved entries. It also covers failure behavior and performance context, making it complete for a complex resolver.

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 the parameters with concrete examples (AAPL, 0000320193, ozempic) and explains what each supported type returns. It also clarifies accepted input formats beyond the schema's terse descriptions.

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

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

The description clearly states the tool's function: resolving a user-spoken name to canonical/official identifiers needed by other tools. It distinguishes from siblings like entity_profile and compare_entities by emphasizing the ID-lookup role and listing concrete user phrasings.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving strong contextual guidance. It does not explicitly list alternative tools to use instead in other cases, but the directive is clear enough for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds the probing process (calls ai_visibility_check, ranks by score) and return fields (score, confidence, signal density), which are not in annotations. This is meaningful added context.

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

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

Four short sentences, each earning its place: action, process, use case, output. No filler or redundant restatement of the schema.

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, but the description explicitly states the return format (ranked list with score, confidence, signal density). It covers purpose, process, and use case adequately for a read-only tool with straightforward parameters. It does not address edge cases like model-specific behavior, but the schema covers that, so this is 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?

The input schema has 100% coverage with descriptions for all four parameters, so the schema does the heavy lifting. The description adds the 'your brand + N competitors' framing for entities, but this is already implied by the schema's 'First entry treated as the subject.' No additional parameter semantics are needed beyond baseline.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by focusing on AI visibility ranking specifically.

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

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

States 'Useful for competitive AI-marketing audits' and gives a concrete example question, providing clear context for when to use. Does not explicitly name alternatives or exclusion criteria, 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, idempotentHint, etc.), the description discloses fan-out behavior, partial failure degradation, a potential 5-30s latency on bundlephobia's first measurement, and the sources_failed field. This adds substantial behavioral context that annotations alone do not 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 longer than two sentences, but every clause earns its place: purpose, data sources, use cases, return fields, ecosystem limits, and latency caveat. It is front-loaded with the core purpose and structured logically without repetition.

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

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

For a composite tool with no output schema, the description fully compensates by enumerating returned summary fields, per-advisory details, links, alternative versions, and partial failure behavior. It also covers ecosystem limitations and latency, making it complete for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage of both parameters, so the description's parameter burden is low. The description does not add much beyond the schema but reinforces the package name semantics with 'npm package name' and implicitly clarifies version behavior through examples. Baseline 3 is appropriate.

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

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

The description opens with a specific verb phrase: a composite 'should I add this npm package to my project' check that fans out across deps.dev and bundlephobia. It clearly identifies the resource (npm package health analysis) and distinguishes this from sibling research tools by emphasizing the single-call composite nature.

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 guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also gives an exclusion boundary by noting NPM ecosystem only in v1 and directing other ecosystems to deps.dev:version directly, which helps agents choose alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extra behavioral context beyond the annotations: it highlights that the tool is 'Keyless' (no authentication required) and explains the return payload structure (accessions, title, organisms, diseases, instruments). This meaningfully supplements the structured 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 two sentences, front-loaded with the main verb and resource, and every clause earns its place. It communicates the repository, keyword scope, return format, and auth requirement without any redundancy or unnecessary detail.

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

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

For a simple 3-parameter read-only search tool with no output schema, the description is complete: it tells the agent what to search, where, what to expect in response, and that no key is required. Pagination details are covered by the schema, so nothing essential is missing.

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

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

Input schema coverage is 100%, so baseline is 3. The description goes further by elaborating on the 'keyword' parameter, listing example categories (disease, organism, technique, protein, instrument) that help the agent construct effective queries. This adds value beyond the schema's brief free-text 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?

Description clearly states it searches the EBI PRIDE Archive for projects by keyword, specifying the exact repository and types of keywords (disease, organism, technique, protein, instrument). It also lists the return fields (accessions, title, organisms, diseases, instruments), making the tool's scope and function unambiguous and distinct from siblings.

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

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

The description provides clear context for when to use the tool (when searching for projects in the EBI PRIDE Archive) and what it returns. It does not explicitly mention alternatives or when-not-to-use conditions, but the specificity of the repository and use case serves as sufficient guidance in the context of the sibling tools.

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

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

Annotations already declare read-only and non-destructive, but the description goes beyond by disclosing specific mechanics (BGE-base-en embeddings, cosine similarity, 500-char overlapping windows), return format (passages with offsets and scores), and the 200K character cap with truncation flagging. This rich context helps the agent predict behavior and handle edge cases without contradicting annotations.

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

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

The description is dense but well-structured: first sentence establishes the core function, second sentence gives the use case, third provides technical details and limits. Every sentence earns its place, and it is front-loaded with the most important information. 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?

Despite having no output schema, the description explains return values (passages with character offsets and similarity scores), the algorithm and windowing approach, size caps, and truncation behavior. It also mentions pairing with a sibling tool, providing a complete picture for safe invocation and result interpretation.

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 reinforces the schema's parameter meanings (e.g., 'Pass the text you already pulled' for text, natural-language query for query) without adding substantial new parameter-level semantics beyond what the schema already provides. No parameter is left unexplained.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific verbs and resource (search inside text). It distinguishes itself from siblings by emphasizing it operates on already-pulled text and even contrasts with ask_pipeworx_grounded, making its niche unambiguous.

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

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

Explicitly states when to use: when the record is too big to fit in the prompt, and provides a concrete alternative/pairing strategy with ask_pipeworx_grounded. The phrase 'Pass the text you already pulled' establishes a clear prerequisite, giving the agent 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?

Discloses rich operational details beyond annotations: OAuth prerequisite, SMS 10/day cap, phone verification, webhook signing secret, and auto-disable after 10 failures. Annotations only indicate non-read-only and idempotent, so the description adds substantial behavioral context.

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

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

The description is dense but front-loaded with the core purpose, then logically organizes subscription types and delivery channels. Though a single long paragraph, every sentence contributes unique information; could be improved with bullet structure but remains appropriately sized.

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

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

With no output schema, the description explicitly states the return value ('Returns the new subscription id') and covers prerequisites, all type variants, and delivery options. It also clarifies edge cases like SMS verification and webhook auto-disable, making it complete for agent decision-making.

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

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

Schema coverage is 100% with detailed descriptions, so baseline is 3. The description adds meaning beyond the schema with examples like 'items:["5.02"] = officer change' and clarifies delivery constraints such as phone verification and caps, which are not fully 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb (Create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Provides clear context: requires OAuth account, lists supported subscription types, and notes the always-on feed with pull alternatives ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json'). It does not explicitly name list_subscriptions or unsubscribe as alternatives, so it falls short of full when-to-use vs alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, so the tool is clearly safe. The description adds valuable behavioral context by explaining the return structure (category buckets, exact tool + argument shape) and that results are 'drawn from the live catalog of thousands of tools.' It also discloses the optional topic parameter's effect. This goes beyond 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 description is a single dense paragraph but front-loads key information and every clause adds value. It could be slightly better structured with sentence breaks, but it remains efficient and readable. It's 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?

For a lightweight, read-only onboarding tool with no output schema, the description is complete: it explains what is returned, how to invoke it (with/without topic), and its role as the 'first' tool to call. It doesn't detail the exact output JSON structure, but that's not essential given the tool's purpose and the absence of 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?

Schema description coverage is 100%, so the single parameter 'topic' is fully documented in the schema, including its allowed values and the omit-for-spread behavior. The description only repeats these examples (finance, pharma, betting) without adding deeper semantics, so it meets the baseline but doesn't elevate beyond it.

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

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

The description clearly states the tool's function: 'Returns category-bucketed example questions... each with the exact tool + argument shape that answers it.' It identifies the resource (Pipeworx capabilities) and distinguishes itself from siblings by explicitly naming it the 'onboarding entry point' and referencing how to call meta-tools. The verb+resource+scope are specific and 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 gives explicit usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the parameter behavior (omit for full spread, pass topic to focus). However, it lacks an explicit when-not-to-use statement or comparisons to sibling tools like discover_tools or ask_pipeworx, so it's clear context but no 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 indicate non-read-only, non-destructive, and idempotent. The description adds valuable context: soft-delete behavior (deactivated not deleted) and that historical events remain available via recent_alerts, going beyond annotations.

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

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

The description is three concise sentences, front-loaded with the core action. No wasted words, each sentence adds essential information.

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

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

Given the tool's simplicity (single parameter, no output schema), the description adequately covers the operation, ownership constraint, and side effects. It is complete for the agent to use 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% and the single parameter 'id' is well-described in the schema as 'Subscription id (uuid) returned by subscribe.' The description only says 'by id', adding minimal 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 uses a specific verb 'Cancel' with a clear resource 'a subscription' and method 'by id'. It clearly distinguishes from siblings like subscribe, list_subscriptions, and recent_alerts.

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: ownership is enforced (you can only cancel your own subscriptions). It implies the right time to use the tool, though it does not explicitly name alternatives 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?

Beyond annotations (readOnly, idempotent, openWorld), the description discloses critical behavioral nuances: the difference between could_not_verify (inconclusive due to tool failure) and unsupported (no source found), the routing between structured and grounded pipelines, and that it returns a verdict with citations. It also clarifies that could_not_verify must not be shown as evidence, which is vital.

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, every sentence serves a purpose: trigger phrases, routing logic, error semantics, and value proposition. The structure is logical and front-loaded with natural-language examples. 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 description fully covers behavior, return values (verdict types, actual value, citation, reasoning), and edge cases (could_not_verify, unsupported). Given the absence of an output schema, the description compensates completely, making the tool's behavior predictable and safe to invoke.

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

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

Schema coverage is 100% with detailed descriptions and examples for both `claim` and `tolerance_pct`. The description largely repeats this information (e.g., tolerance override) without adding new semantic meaning. It adds a usage example but no substantive parameter guidance beyond the schema, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific trigger examples ("Is it true that…", "fact check") and distinguishes it from sibling tools by explaining it replaces 4–6 sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR fast path) and all other claims (grounded pipeline), and notes when it should not be used (e.g., could_not_verify means the check did not happen, not evidence).

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