Septa

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds key traits: it makes external API calls (Anthropic if key provided), returns per-model scores with response details. No contradiction and enriches agent understanding.

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 core action, then model/API details, then returns and use cases. No wasted words; every sentence adds value.

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

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

No output schema, but description fully covers return format (per-model fields, combined view). Also explains optional parameters, authentication, and purposes. Sufficient for an LLM 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%, baseline 3. Description adds substantial meaning: examples for 'entity', model options with defaults and key requirement, purpose of 'context' for disambiguation. Greatly aids correct parameter usage.

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 ('probe') and resource ('LLMs') to state it scores visibility (0-100) per model. Distinguishes from siblings like 'scan_competitor_ai_presence' by being broader (any entity). No ambiguity.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model vs. BYO key. Lacks explicit when-not-to-use or comparison to siblings, but context 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 destructiveHint. The description adds meaningful behavioral context: it returns citations (pipeworx:// URIs), works on every tier, and is a single fast call. It does not contradict annotations, and the added details inform the agent about expected outputs and performance.

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 most but well-structured, opening with a strong directive, then listing covered domains, examples, and upgrade paths. Every sentence contributes value, though it could be trimmed (e.g., repeating 'ask_pipeworx'). It front-loads the most important guidance.

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

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

For a router tool with broad scope, the description covers all essential aspects: what it does, when to use it, examples, and how it compares to alternatives. It lacks details on error handling or rate limits, but given the tool's nature and annotations, the description is sufficiently complete.

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

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

Schema description coverage is 100%; the schema already documents the 'question' parameter and its aliases. The description adds examples of valid queries but no further parameter-specific semantics. Baseline 3 is appropriate when the schema carries the semantic load.

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: 'Routes the question to the right one of 5,366 tools across 1396 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses a specific verb (routes) and resource (verified sources), and distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs when to use: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions.' Also provides exclusions and alternatives: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is clear, actionable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, providing the safety profile. The description adds valuable behavioral context: it's a live experiment where routing may change when a candidate is under test, and it currently matches ask_pipeworx exactly. No contradiction detected.

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 efficiently structured, front-loading the beta status, then explaining current equivalence, usage, and experimental nature. Each sentence contributes new information with no wasted words; the length is appropriate for the nuance required.

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 provides enough context for an agent to choose this over ask_pipeworx by explaining its experimental nature and current state. It references the shared response shape, compensating for the absent output schema, though it assumes familiarity with ask_pipeworx for full parameter/output understanding.

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 of the six parameters documented as aliases for 'question.' The description adds no parameter-specific semantics beyond noting 'same arguments' as ask_pipeworx, which is redundant given the schema already does the heavy lifting.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,366 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing the experimental routing improvements, making its purpose unmistakable.

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

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

The description explicitly directs users to 'Use it exactly like ask_pipeworx when you want the newest routing,' naming the stable sibling as the comparison point. It doesn't enumerate alternatives like ask_pipeworx_grounded or state exclusions, but the context 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?

Beyond the annotations, the description adds a detailed success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and enumerates all refusal_reason values. It also discloses the extra LLM call cost and the constraint that answers come only from tool results. 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?

Every sentence carries valuable information: high-stakes use case, success and refusal structures, use guidance, and cost tradeoff. The description is front-loaded with the key differentiator and remains structured despite its length.

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

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

Despite having no output schema, the description fully specifies the return envelope and all possible refusal reasons, which is essential for agent decision-making. The complexity is high but the description covers the required invocation and post-invocation context completely.

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

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

The input schema fully documents the single semantic parameter 'question' and all five aliases, achieving 100% coverage. The description does not add parameter-specific details beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb+resource: 'Hallucination-resistant answer mode' that extracts answers using only tool results. It clearly distinguishes from sibling ask_pipeworx by emphasizing grounded answers and explicit refusal behavior. The purpose is unambiguous and differentiates well.

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

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

The description explicitly says when to use: 'whenever an answer will be quoted, cited, or acted on... must not invent facts.' It also gives the alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This is exemplary usage guidance.

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

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

Description extensively discloses behaviors beyond annotations: resolution matching confidence, fan-out logic per category, safety short-circuits for low-confidence/closed markets, wide spread handling, cancellation rule parsing, and news fallback. Annotations (readOnlyHint, idempotentHint) already indicate safeness, but description adds critical operational 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?

Description is long but well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Front-loaded with purpose and usage. Every section adds necessary information; no redundancy. Could be slightly more concise but density is high.

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, so description carries full burden. It thoroughly covers return values (result.market, analysis, evidence), error/safety states (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread), and resolution rules. Addresses all relevant aspects for an agent to correctly 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%, so baseline is 3. Description adds significant value with examples for 'market' (slug, URL, text), behavior explanation for 'depth' (quick vs thorough), and context for 'include_raw' (when to use true/false). Exceeds basic schema descriptions.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call. Specifies input types (slug, URL, question text) and output (evidence packet + comparison). Distinguishes from sibling tools by emphasizing comprehensive one-call research.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides clear context for when to use the tool, though does not explicitly contrast with alternatives like polymarket_edges.

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 readOnlyHint, openWorldHint, idempotentHint. The description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is fairly concise but slightly verbose with examples and details. However, every sentence serves a purpose, and the most important info is front-loaded (examples, preference advice).

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 (2 params, no output schema), the description covers input interpretation, data sources, behavior (sorting), and output format (paired data + URIs). It is complete for an agent to use effectively.

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

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

Schema coverage is 100%, but the description adds value by explaining the types of data pulled for each type and giving concrete examples for values (e.g., tickers, drug names). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It uses natural language examples and emphasizes preference over sequential lookups, distinguishing it from sibling tools like entity_profile.

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

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

Explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups' and replaces 8-15 sequential lookups. Provides example queries and supported entity types, making it clear when to use this tool.

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

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

Despite annotations already marking readOnly/openWorld/idempotent, the description adds rich behavioral context: gaps[] for unanswered facets, contradictions[] for standard/thorough, citation format, semantic excerpting, latency expectations, and depth-tier behavior. This goes far beyond the structured annotations and is internally consistent.

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 each sentence earns its place. It is logically organized: account requirement, core capability, best-use cases, alternatives, depth behavior, return format, and timing. Critical operational details are front-loaded (e.g., account needed) and the structure makes the complexity navigable.

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

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

Given no output schema, the description thoroughly covers return values (findings packet, verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop fields) and behavior (multi-hop, semantic excerpting, latency). It addresses edge cases like news queries returning empty gaps and the need for paid tier. This is a complete picture of 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 both parameters are already well-described. The description adds the critical parameter-specific constraint that depth:'thorough' requires a paid plan, and clarifies that the question can be broad/multi-part. That extra constraint justifies a score above baseline 3, though most semantic weight is carried 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's function: grounded multi-source research across 1396 structured data sources via parallel decomposition, distinguishing it from open-web search and sibling ask_pipeworx. It specifically says 'this is NOT open-web search' and gives concrete examples of best-fit questions.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also specifies the sign-in prerequisite and directs unsigned users to ask_pipeworx.

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

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

Annotations already provide readOnly, idempotent, non-destructive hints. The description adds valuable behavioral context: returns top-N tools with schemas and examples, ready to call directly, no second lookup needed. No contradictions.

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

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

Description is efficiently front-loaded with purpose, then usage, then return format. Every sentence provides unique value; no wasted words.

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

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

Given the low complexity and high schema coverage, the description fully explains input (natural language query), output (list with schemas), and usage context. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples and clarifies it accepts natural language, but does not significantly add parameter meaning beyond the schema definitions.

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

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

The description clearly states it discovers tools by task description, listing many domains. It explicitly distinguishes from sibling tools by advising to call this first when many tools exist.

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

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

Provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' Implicitly tells when not to use (when you already know the tool).

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds detailed behavioral context: it fans out across multiple APIs (SEC, XBRL, USPTO, news, GLEIF), returns specific fields (cik, filings, fundamentals, patents, news, LEI), and notes that the patents source 'soft-fails until reactivated'. This goes beyond annotations to give a transparent picture of tool 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 packed with useful information and front-loaded with example queries. Every sentence adds value. However, it is somewhat verbose (multiple lines, including details like the patents sunset date and fallback behavior). Could be tightened slightly without losing clarity, but overall it is well-structured for an AI agent.

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

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

Given the tool's complexity (multiple data sources, specific return fields) and the lack of an output schema, the description is quite thorough. It lists what is returned (filings, fundamentals, patents, news, LEI) and notes edge cases (patents soft-fail). The only minor gap is no mention of error handling or performance characteristics, but the annotations cover idempotency and safety. Overall, it provides sufficient contextual completeness.

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

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

The input schema already describes both parameters thoroughly (type enum, value as ticker/CIK). The description reinforces this with examples ('AAPL', '0000320193') and explicitly states that names are not supported. This adds meaningful usage context beyond the schema, but the schema itself is already strong (100% coverage), so 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 clearly states the tool's purpose: a holistic, multi-source profile of a US public company. It provides concrete example queries ('Tell me about X', 'research Acme'), lists the combined data sources, and distinguishes it from single-source lookups. This makes the purpose immediately understandable and distinguishable from sibling tools like resolve_entity.

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

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

The description explicitly advises when to use this tool: 'ALWAYS PREFER over chaining single-pack [...] lookups when the user asks for a holistic view.' It also specifies the input format (ticker or CIK) and warns that names are not supported, directing the user to resolve_entity first. This provides clear guidance on usage and alternatives.

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

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

Annotations already declare destructiveHint=true, and the description confirms deletion. Adds context about clearing sensitive data. No contradiction with annotations.

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

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

Two concise sentences with front-loaded purpose. No extraneous content.

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 destructive tool with no output schema, the description provides complete guidance: purpose, usage, and relationships to siblings.

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

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

Schema coverage is 100% for the single parameter 'key', with description matching. The description adds no new information beyond schema, resulting in a baseline score.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. Distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides pairing guidance with 'remember and recall'.

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 readOnlyHint (true), openWorldHint (true), idempotentHint (true), destructiveHint (false). Description adds behavioral steps: fetches page, extracts data, emits standard markdown format. No contradictions.

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

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

Two sentences: first defines purpose and audience, second lists use cases. Every sentence adds value, no redundancy. Front-loaded with key 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?

With 2 parameters, no output schema, and rich annotations, description covers main behavior and output format. Minor gap: no mention of error handling or URL validation, but sufficient for typical use.

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

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

Schema covers both parameters with descriptions (100% coverage). Description repeats 'any URL' and implies max_links via 'Maximum number of link entries', but adds no new semantic details 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?

Clearly states the verb 'generate', resource 'llms.txt file', and target audience 'AI crawlers'. Distinguishes from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on file generation.

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

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

Explicitly lists three use cases: getting client site indexed, drafting own llms.txt, auditing competitor. Does not explicitly mention when not to use or compare to alternatives, but context is clear.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. Description adds return field details but no additional behavioral traits like pagination.

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

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

Two efficient sentences: first covers purpose and output, second gives usage guidance. No unnecessary words.

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

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

Covers purpose, output fields, and usage. Missing output schema is not critical for a simple list. Could mention scope (caller's subscriptions) already included.

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 sole parameter include_inactive is well-documented in the schema. Description adds no further meaning; schema coverage is 100%, so baseline 3.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields, distinguishing it from sibling tools 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?

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Does not list alternatives but provides clear context.

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

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

The description adds behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. There is 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?

Every sentence adds value. The description is well-structured: purpose first, then usage guidelines, then limitations. It is appropriately sized for the complexity of the tool.

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

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

Given the tool has 3 parameters (one nested object) and no output schema, the description is very complete. It explains each parameter's purpose, constraints, and the context object fields. It also mentions rate limits and quota, leaving no gaps.

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

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

Schema coverage is 100%. The description reinforces enum meanings and adds usage guidance (e.g., be specific, don't paste user prompt), which adds value beyond the schema definitions.

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 is for sending feedback to the Pipeworx team. It enumerates specific categories (bug, feature, data_gap, praise) with definitions, distinguishing it from the sibling tools which are mostly data retrieval and inquiry tools.

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

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

The description explicitly states when to use the tool: for bugs, feature requests, data gaps, or praise. It also tells what not to do: 'don't paste the end-user's prompt.' This provides clear guidance on appropriate usage.

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

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

Discloses caching behavior (5min-1h), data source (CF analytics-engine), privacy (no PII), and nature (self-aggregating signal). This goes well beyond the annotations, which only mark read-only, idempotent, and non-destructive traits.

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

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

Description is concise (5 lines), structured with bullet points, and front-loads the key output. Every sentence adds value without repetition or fluff.

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

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

Returns are described (top tools, top packs, call volume) but not in exact format (e.g., names with counts or ordering). For a read-only query tool without output schema, this is sufficient but could hint at structure (e.g., array of objects).

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

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

Schema has 100% coverage with one parameter. The description adds semantic guidance on window selection (shorter windows surface what's hot, longer show steady-state demand), which helps agents choose wisely beyond the enum values.

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 returns top tools, top packs, and total call volume over a configurable window. The verb 'Returns' with specific resources makes the purpose unambiguous and distinguishes it from siblings like 'discover_tools' which likely returns all tools, not trending ones.

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?

Three explicit use cases are provided, giving clear context for when to use this tool. However, it does not explicitly state when not to use it or name alternative tools for other scenarios, which would elevate it further.

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?

Disclosures go far beyond annotations: details semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slugs), fill check against live CLOB depth, edge cases like thin legs. All consistent with readOnlyHint and idempotentHint.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value. Could trim minor redundancy but overall compact for the complexity.

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

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

Given the tool's complexity (arbitrage detection in prediction markets with multiple modes and edge cases), the description is remarkably complete. Covers inputs, modes, internal filters, output format, and references sibling tools. No output schema but response fields are described.

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 describes event and topic with good coverage, but description adds substantial meaning: explains event slug format, topic as seed question, unmentioned no-args mode. Clarifies that event mode includes partition_check response and fill_check logic.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three execution modes (no args for trending_scan, event for specific market, topic for cross-event) with precise definitions.

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 instructions on when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides guidance on when not to trade (realizable_edge_pp <= 0). Covers alternatives like custom sizing via polymarket_fill_risk.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses caching ('Cached 1h at the KV level'), filtering logic, tradeable-edge knobs, diagnostics, and edge calculation (net of slippage, Kelly caps). This provides substantial behavioral context beyond what annotations offer.

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 lengthy but appropriately detailed given the tool's complexity. It front-loads the purpose and logically structures technical details. However, some sections (e.g., model families) could be streamlined without losing clarity.

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

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

Despite lacking an output schema, the description fully explains the response structure (by_segment, diagnostics, fed_candidates) and each segment's criteria. It is complete enough for an AI agent to understand all capabilities.

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

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

Schema coverage is 100%, and the description enriches each parameter with rationale and interaction details. For example, slippage_pp explains Polymarket's fee structure and advises on adjustment; min_partition_leg_kelly explains why min_kelly doesn't filter partitions. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides context on when to use the tool ('what should I bet on today') and explains tradeable-edge knobs. It also notes that Fed bets are excluded from ranking, giving some exclusion guidance. However, it lacks explicit comparisons to alternatives or when not to use it.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial value by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining how decay (trend, decay_pp_per_day) is computed, noting that decay is based on daily closes (not intraday), and clarifying data gaps from snapshot creation. 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 well-structured, starting with purpose, then detailing the response structure, and ending with limits. It is somewhat lengthy but every sentence provides useful information. No redundant or wasted text. It could be slightly more concise, but overall efficient.

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

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

There is no output schema, so the description must explain the return values. It does so thoroughly: tracked[], expired[], snapshot_dates[] with their sub-fields and meanings. It also covers important context like the 60-day TTL, data gaps, and the fact that snapshots are written on cache-miss. This is comprehensive 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%, with clear descriptions for both parameters (days and window). The description adds default values and constraints (days default 14, max 30; window default '1wk') and explains the meaning of window as 'snapshot family,' but this does not significantly extend the schema's own descriptions. Hence 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 explicitly states the tool's purpose: tracking edge persistence and decay using daily polymarket_edges snapshots. It uses the verb 'answers' and specifies the resource ('polymarket_edges snapshots'), clearly differentiating from sibling tools like 'polymarket_edges' (the raw snapshot source) and others.

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

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

The description provides clear context on when to use the tool: to distinguish between a fresh wide edge and an older one that persists. It explains the significance of freshness and mentions limits like a 60-day TTL and data gaps. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint=true, etc. The description goes beyond by describing the ladder-walking behavior, specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and basket-mode details like forced directional risk. There is no contradiction with annotations.

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

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

The description is dense with useful information and front-loaded with the core purpose. While somewhat long, every sentence adds value for understanding the complex tool, so it is appropriately structured.

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

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

Given the complexity of single-market vs basket modes, the lack of an output schema, and 4 parameters, the description covers output fields explicitly, compensates for missing schema, and explains verdict states, thin legs, and clamping, making it complete.

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

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

Schema description coverage is 100%, and the description adds significant value by explaining side defaults, the meaning of size_usd for buys vs sells and basket mode, and the distinction between market and event parameters.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly says to use it 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' differentiating from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit when-to-use guidance (for arb signals and trades above $500) and explains why partial fills are dangerous. It details the two modes and required parameters, and warns about the dominant loss mode, offering clear context for use.

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

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

Beyond annotations (readOnlyHint, etc.), the description reveals significant behavioral details: two operational modes, response structure with leg-by-leg prices and spreads, and safety fields explaining when spreads are invalid (incompatible bet shapes, temporal misalignment, or unrelated events). It clearly communicates tool limitations and edge cases.

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

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

The description is detailed but well-organized with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though the length is substantial. It could be slightly more compact, but the structure aids readability.

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 fully explains the response (leg-by-leg prices, top spreads, safety fields) and covers all necessary context for correct usage: modes, parameter interaction, and warning conditions. It leaves no significant gaps for this complex tool.

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

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

Schema coverage is 100% with each parameter described. The description adds context beyond schema definitions: it explains the two modes (topic vs explicit) and how they override each other, and provides examples. This enriches parameter understanding, earning above the baseline of 3.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings by focusing on this specific venue pair and mentions two modes (topic and explicit tickers), providing a precise verb+resource.

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

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

The description explains when to use the tool (comparing spreads across venues) and provides guidance on interpreting results via safety fields (compatibility_warning, temporal_alignment). It warns that pre-mapped topics often return warnings, implying cautious use. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage, leaving some ambiguity about when to choose one over the other.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and pairing behavior. No contradictions. Adds context beyond annotations.

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

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

Three sentences, each with distinct purpose: first describes retrieval action, second explains typical use cases, third outlines scoping and pairing. No wasted words, front-loaded with primary function.

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?

Tool is simple with one optional parameter and no output schema. Description covers core behavior, scoping, and integration with siblings. No missing information needed 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% with a clear description for the sole parameter. Description restates the same idea: retrieve by key or list all if omitted. Schema already does the heavy lifting, so description adds minimal new 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?

Clearly states the tool retrieves a value by key or lists all saved keys. Distinguishes from sibling tools remember and forget by explicitly pairing with them. Verb+resource is specific: 'Retrieve a value previously saved via remember, or list all saved keys.'

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 describes when to use: to look up context stored earlier without re-deriving. Implicitly indicates when not to use (saving or deleting) by referencing remember and forget. Also mentions scoping to agent identifier.

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?

There is a contradiction: annotations set readOnlyHint=true, indicating no system state modification, but the description states that setting mark_read:true flags returned events as read, which is a state change. This directly contradicts the annotation, scoring 1 per instructions.

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

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

The description is a single paragraph, efficient with no wasted words. The main purpose is front-loaded. Mention of the raw URL is slightly extraneous but not damaging.

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

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

No output schema exists, so description should compensate. It mentions return fields (source, citation_uri, payload) but lacks full structure details, error cases, or examples. It is adequate but not comprehensive for a 5-parameter 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%, baseline 3. The description adds context beyond schema descriptions by explaining the purpose of mark_read (flag events as read) and the filtering parameters. It integrates the parameters into a usage narrative, adding value.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource and action. It mentions key return fields like source, citation_uri, and payload. However, it does not explicitly differentiate from sibling tools like 'recent_changes', making it slightly less than a 5.

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

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

The description provides clear context on filtering by type and since, and explains the mark_read flag usage. It also mentions polling suitability and an alternative raw URL. However, it lacks explicit 'when not to use' guidance or comparison with sibling tools, preventing a top score.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds substantial behavioral context: it fans out to multiple sources in parallel, handles rate limiting with a fallback, and documents the return structure (changes[] grouped by source, total_changes, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph that front-loads example queries and packs in many details. While dense, it is efficient and avoids redundancy. A slight trim or structuring into bullet points could improve readability, but it remains concise.

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

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

The description is fairly complete given the tool's complexity. It explains the return structure and sources. However, it lacks details on error handling or behavior when all sources fail. With no output schema, the description carries the burden, and it mostly succeeds.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra value by providing examples for 'since' (ISO date and relative shorthand, with default recommendation '30d' or '1m') and clarifying input formats for 'value' (ticker or CIK). This enriches the parameter meaning beyond the schema.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists the data sources (SEC EDGAR, GDELT→GNews, USPTO). It distinguishes from the sibling tool 'entity_profile' which is for static profiles.

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 when-to-use guidance is given: 'Use entity_profile instead when you want the static profile...' The description also provides example queries and explains fallback behavior (GDELT preferred, GNews on rate limit, USPTO soft-fail).

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 idempotentHint=true and destructiveHint=false. The description adds valuable context beyond annotations: key-value scoping by identifier, persistence differences for authenticated vs. anonymous users (24-hour retention for anonymous), and the ability to overwrite keys.

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 well-structured sentences: first states purpose, second provides usage guidance, third adds behavioral details. No redundant information; every sentence serves a distinct role.

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

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

Given the simple parameter structure (2 required strings, no enums, no output schema), the description adequately covers all needed context: what data to store, how keys are scoped, retention policies, and relationships to sibling tools recall and forget.

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 detailed descriptions for both key and value parameters. The description adds typical usage examples (e.g., 'subject_property', 'target_ticker') but does not significantly enhance the meaning already provided by 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 explicitly states the tool saves data for later reuse, listing specific examples (resolved ticker, target address, user preference). It distinguishes from siblings recall and forget, clearly defining its role in the memory workflow.

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 when-to-use guidance: 'Use when you discover something worth carrying forward'. It also explicitly mentions pairing with recall for retrieval and forget for deletion, offering context-sensitive 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 safe read-only, idempotent, non-destructive behavior. Description adds value by noting internal multi-endpoint cascading (replaces 2-3 lookups), which enriches understanding of its operation.

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

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

Single paragraph but well-organized: starts with example queries, states purpose, then details types and outputs. Could benefit from bullet points for readability, but no redundant sentences.

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 fully details return values (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug) and input flexibility. Agent can fully understand what to expect.

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

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

Schema coverage is 100% and includes descriptions for both parameters. The description enhances schema by providing concrete examples (e.g., 'AAPL', '0000320193', 'ozempic') and explaining accepted input variants per type.

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 verbs like 'resolve' and provides clear examples (ticker, CIK, RxCUI) and explicitly states the purpose: map a name to a canonical identifier. It clearly distinguishes from sibling tools by focusing on entity resolution.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', giving clear usage context. Lacks explicit when-not-to-use or alternatives, but the context is strong enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that it probes networks, treats first entity as subject, and returns scores/confidence/signal density. No contradictions; adds useful behavioral context beyond annotations.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value. No filler; highly concise.

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 (4 params, 1 required, no output schema), the description covers the purpose, inputs, output format, and an example. Lacks edge cases but sufficient for an agent.

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

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

Schema description coverage is 100%, but the description adds semantic details: first entity as subject, supported models with defaults, and API key usage. This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes with ai_visibility_check, and returns a ranked list. It distinguishes from siblings like ai_visibility_check by focusing on multi-entity comparison, but does not explicitly contrast with compare_entities.

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

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

The description provides a use case (competitive AI-marketing audits) and an example query, but lacks explicit guidance on when not to use it or alternatives (e.g., single entity check via ai_visibility_check). Provides implied context but no when-not-to-use.

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. Description adds behavioral details beyond annotations: it bundles two APIs, explains graceful degradation (sources_failed list if bundlephobia times out), and mentions timing (5-30s first measurement). No contradictions.

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

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

The description is informative but slightly verbose, especially the first sentence. However, it is well-structured with separate sections for purpose, usage, and edge cases. Front-loaded with the composite nature.

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 high-quality annotations, no output schema, and 100% schema coverage, the description covers all necessary aspects: purpose, usage, behavioral traits, failure modes, and ecosystem scope. No gaps remain 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 description coverage is 100% for both parameters. The description adds some context (default version behavior, output summary fields) but does not significantly enhance parameter understanding 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 it's a composite check for adding npm packages, combining deps.dev and bundlephobia. It uses specific verbs ('check', 'fans out') and resource ('npm package'), and distinguishes from sibling tools by emphasizing its all-in-one nature and ecosystem 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?

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clearly states ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' Includes when-not-to-use.

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 idempotent, read-only, non-destructive behavior. The description adds transparency about the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char limit with truncation and flagging, and that results include character offsets and similarity scores. No contradiction with annotations.

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

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

The description is 4-5 sentences, front-loaded with the core purpose and use case. It efficiently conveys multiple details (use case, pairing, technical specs) without redundancy, though the technical details could be slightly more integrated.

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, but the description explicitly states return values (top-N passages with character offsets and similarity scores). It also covers limitations (200K char cap, truncation) and integration with sibling tools, making it fully contextual.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description reinforces the max char limit for 'text', the default and range for 'limit', and provides natural-language examples for 'query' (e.g., 'supply-chain risk'), adding 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 tool name and title clearly indicate a search within a source. The description specifies it performs semantic search inside a fetched record, and distinguishes it from siblings by mentioning its pairing with ask_pipeworx_grounded and contrast with fetching whole documents.

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 this tool: when a record is too large for the prompt. It provides guidance on how it saves context and returns only relevant passages with offsets, and mentions pairing with another tool for grounded verification.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns alerts, advisories, detours, and suspensions, and explains route format. No contradictions. It doesn't mention pagination, but annotations suffice.

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 only two sentences, front-loaded with the purpose, then providing detailed usage examples. Every sentence is necessary and well-structured.

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

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

With one optional parameter, no output schema, and comprehensive annotations, the description covers all necessary information. It explains the return type (alerts/advisories) and usage clearly. No gaps remain.

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

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

Schema coverage is 100%, and the description adds significant value by providing examples (e.g., 'Paoli/Thorndale', '23', 'NHSL') and explaining the optional nature of the route parameter. This goes beyond the schema's brief description.

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

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

The description specifies the exact purpose: retrieving SEPTA service alerts, advisories, detours, and suspensions. It clearly distinguishes from sibling tools like 'septa_bus_positions' and 'septa_next_to_arrive' by focusing on alerts, not real-time positions or arrivals.

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

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

The description explains when to pass a route (to check one line) and when to omit (to list all active alerts). It provides concrete examples of valid route formats. While it doesn't explicitly state when not to use it versus siblings, the examples and context make usage clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral details: data is live, includes crowding estimates, and legacy trolley numbers are auto-translated. No contradictions with annotations.

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

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

The description is extremely concise: two sentences plus an example call. It front-loads the core purpose and data returned, with every sentence adding necessary information. No fluff or redundancy.

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

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

Given there is no output schema, the description compensates by listing all key return fields (direction, destination, next stop, etc.). It adequately covers the input and provides examples. Minor omission: no mention of error handling or data freshness guarantee, but overall complete for a simple read-only tool.

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

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

The schema covers 100% of the parameter with a clear description and examples. The description adds extra semantic detail by explaining auto-translation of legacy trolley numbers and reinforcing the accepted route formats, providing 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 the tool's purpose: live SEPTA bus/trolley vehicle positions for a given route. It specifies the exact data returned (direction, destination, next stop, etc.) and distinguishes from sibling tools (e.g., septa_alerts, septa_next_to_arrive) by focusing on positions rather than alerts or arrivals.

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 (for live vehicle positions) and gives examples. However, it does not explicitly explain when not to use it or contrast with alternatives (like septa_next_to_arrive for arrival times). The sibling tools are listed but not referenced in the description.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. The description adds valuable behavioral context: 'direct trains and connecting itineraries (with transfer station), departure/arrival times, live delay status', and notes fuzzy matching for station names. This goes well beyond the annotations, fully disclosing what the tool does and its capabilities.

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 only two sentences plus an example, with no wasted words. It front-loads the core functionality and immediately gives a concrete usage example. Every sentence earns its place, making it highly efficient for an agent to parse.

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 (querying schedule and live status with transfers), the description covers all essential aspects: what it does, how to use it (example), key parameters, and behavior (fuzzy matching, live delay). There is no output schema, so the description adequately informs the agent about the return content without needing excessive detail.

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

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

Input schema covers 100% parameter descriptions, so the baseline is 3. The description adds context by including an example with specific station names and explaining fuzzy matching, which helps the agent understand parameter values. It also notes the default for 'n' (3). This adds meaningful guidance beyond the schema.

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

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

The description clearly states the tool's purpose: 'Next SEPTA Regional Rail trains from an origin station to a destination station in Philly — direct trains and connecting itineraries (with transfer station), departure/arrival times, and live delay status.' It distinguishes itself from sibling tools like septa_alerts and septa_train_view by focusing on the 'next to arrive' functionality and includes an example call.

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 answers 'when is the next train from X to Y in Philadelphia' and includes a concrete example. It implies usage for Regional Rail queries but does not explicitly state when not to use it or mention alternative tools for other transit modes (e.g., buses). The guidance is clear but could be more specific about 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds meaningful behavioral details beyond annotations: it explains the grouping (Northbound/Southbound), the fields returned (train number, line, destination, scheduled/estimated times, live status, track), and the forgiving station name matching. It does not contradict annotations.

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

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

The description is three sentences: a clear statement of purpose, a list of returned fields, and an example call. Every sentence is informative and necessary. 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?

Given the tool's simplicity (2 parameters, no output schema), the description fully covers input (station, results with defaults and max), output (all relevant departure fields including live status), and behavior (fuzzy matching, grouping, example). It is self-contained and does not rely on external docs.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example call with both parameters ('station' and 'results') and clarifying that station names are fuzzy-matched. This enhances understanding beyond the schema's field descriptions.

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

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

The description clearly states it returns a 'Philadelphia SEPTA Regional Rail departures board for a station' with specific details (grouped Northbound/Southbound, train number, line, destination, times, status, track). It distinguishes itself from sibling tools by focusing on departures from a station, but does not explicitly contrast with similar tools like septa_next_to_arrive or septa_train_view. The slight mismatch between title 'arrivals' and description 'departures board' causes minor confusion.

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 does not provide guidance on when to use this tool versus alternatives such as septa_next_to_arrive, septa_bus_positions, or septa_train_view. It implies usage for rail station departures but offers no exclusions or comparative context, leaving the agent without 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds what data is returned but does not reveal additional behavioral traits beyond what annotations provide.

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

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

Two concise sentences plus an example. Every word adds value, no redundancy, and purpose 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?

Despite no output schema, the description enumerates return fields (train number, line, destination, current/next stop, minutes late, lat/lon) and covers core use cases. Parameter handling is clear.

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

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

With 100% schema coverage on a single parameter, the description adds value by clarifying the 'line' parameter is optional and showing an example call. This goes beyond the schema description alone.

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

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

The description clearly states the tool provides live positions of SEPTA Regional Rail trains, listing specific data fields (train number, line, destination, etc.) and answers two common questions. This distinguishes it from sibling tools like septa_bus_positions or septa_next_to_arrive.

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 example queries and mentions optional line filtering, which implies usage context. However, it does not explicitly state when not to use this tool or suggest alternatives among the many SEPTA-related siblings.

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

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

Discloses behavioral traits beyond annotations: subscription creation is not read-only, idempotent (creates distinct subscriptions), delivery channel details (always-on feed, optional channels with caps and verification requirements), and webhook auto-disable after failures. 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?

Well-structured and front-loaded with main purpose and return value. Every sentence is informative, though slightly verbose for a tool description. Could be more concise without losing critical details.

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

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

Given complexity (nested objects, multiple types, delivery options) and no output schema, the description fully covers prerequisites, parameter semantics, and behavioral constraints. Agent can understand tool functionality without external documentation.

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

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

Schema coverage is 100%, and description adds extensive meaning: explains each enum value for 'type', provides detailed type-specific parameter structures for 'params', and describes each delivery field with examples, constraints, and behavioral notes (e.g., 'phone must be verified', '10/day cap').

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 and resource. Distinguishes from siblings like list_subscriptions and unsubscribe by mentioning it returns a new subscription id.

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

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

Provides prerequisites ('Requires a Pipeworx OAuth account'), supported types with examples, and delivery channels. Does not explicitly mention when not to use the tool or compare to alternatives, but gives enough context for appropriate use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. The description adds useful context: it draws from a live catalog and returns tool+argument shapes, which explains the tool's dynamic nature.

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

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

The description is comprehensive and front-loads the key trigger phrases. However, it is somewhat long and could be slightly more concise without losing clarity.

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

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

The description fully explains what the tool returns (category-bucketed examples with tool+argument shapes) and how to use it, which is sufficient given no output schema and the simple parameter.

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

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

Schema coverage is 100% and the description does not add significant meaning beyond the schema's description of the 'topic' parameter. The description gives examples but that is already implied 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 returns example questions to help users understand Pipeworx's capabilities. It distinguishes itself from other tools by being the onboarding entry point and specifies the resource ('Pipeworx') and verb ('suggest questions').

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

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

Explicitly says to use this tool 'FIRST when you do not yet know what Pipeworx can do', and provides clear guidance on calling with no arguments for full spread or with a topic to focus. Also mentions it can be used to learn meta-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?

The description adds important traits beyond annotations: ownership enforcement (only self-cancel) and a non-destructive soft-delete approach (deactivated, not deleted, with data retained for recent_alerts). Annotations indicate non-destructive and idempotent, which aligns. No contradiction.

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

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

Two short sentences, no redundancy. First sentence clearly states purpose; second adds vital behavioral context. Every word earns its place.

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

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

For a single-parameter tool with no output schema, the description covers: purpose, ownership, effect type (deactivation vs deletion), and ties to 'recent_alerts'. Annotations cover safety. No gaps.

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

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

The schema has 100% coverage with description 'Subscription id (uuid) returned by subscribe.' The tool description merely says 'by id', adding no new 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 explicitly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are clear. It distinguishes from sibling tool 'subscribe' by referencing the id returned by subscribe.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation vs deletion behavior. It implies when to use (to cancel your own subscription) and mentions 'recent_alerts' for historical events, but it does not explicitly contrast with other sibling tools or state when not to use.

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

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

The description adds significant behavioral detail beyond annotations: it explains the two pipeline paths (structured SEC EDGAR vs. grounded live sources), the return format (verdict types, evidence with citations), and the tolerance override behavior. It also states idempotency via annotations and discloses that it is read-only and non-destructive, with no contradictions.

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

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

The description is thorough but somewhat verbose. It frontloads examples and then details pipeline behavior, which is good. However, it could be more concise by trimming the examples and pipeline details without losing clarity. Every sentence adds value, but the overall length could be reduced.

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, lack of output schema, and rich input schema, the description is complete. It explains the return values (verdict, actual value, citation, reasoning) and the two processing paths. No missing information for effective usage.

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

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

Schema coverage is 100%, so the schema already describes both parameters well. The description adds value by explaining the tolerance_pct override semantics (overrides implied wording, capped at 5%) and its use case for hallucination detection. It reinforces the claim parameter's natural-language nature with examples, which is helpful but not essential.

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 using authoritative sources. It provides specific examples of user queries (e.g., 'fact check', 'verify the claim that…') and distinguishes itself by noting it replaces 4–6 sequential calls, which helps differentiate from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), giving context on when to invoke this tool. However, it does not explicitly state when not to use it or mention alternatives, though the sibling list implies other research tools exist.

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