Poetrydb

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

Description adds significant behavioral context beyond annotations: explains default model, API key handling (passed through to Anthropic), cost implications, and return structure. Annotations already indicate readOnly, idempotent, openWorld, non-destructive; description confirms and enriches without contradiction.

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

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

Three sentences clearly convey purpose, parameters, and use cases. No redundant information. Front-loaded with the main action and result.

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

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

Despite no output schema, description explains return format (per-model fields + combined view). Covers authentication, free vs paid, and typical use cases. All parameter behaviors are fully 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?

All 4 parameters have schema descriptions (100% coverage). Description adds value by explaining default model, supported models list, API key passthrough behavior, and context disambiguation. It goes beyond schema with usage examples and clarifications.

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 probes LLMs for brand visibility and scores it (0-100). It specifies the default free model and the optional Anthropic model with API key. It distinguishes from siblings by focusing on multi-model visibility scoring for marketing audits.

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?

Description lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly exclude other uses or compare to sibling tools like ask_pipeworx, but the context is clear.

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

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

The description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false) and adds valuable context beyond them: it tells the agent the tool routes internally, fills arguments automatically, returns structured answers with pipeworx:// citation URIs, and works on all tiers with 'one fast call'. It does not contradict annotations, so annotation_contradiction is false. The minor deduction is because it doesn't explicitly state rate limit behavior or what happens if the underlying tools fail, though the broad coverage makes this acceptable.

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 highly efficient and well-structured, using bold for key instructions, synonyms, and examples. Every sentence adds value, from the prioritization statement to the step-up guidance. It's front-loaded with the most critical information and progressively provides detail, with 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 complexity of this tool (dispatching across 5,564 tools), the description is remarkably complete. It explains the domain coverage (authoritative structured data with citations), provides multiple examples, and gives clear usage boundaries. No output schema is needed as the description covers the return format (structured answer with citation URIs). The response guidance about stepping up to grounded or deep research completes the picture.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining what the single parameter (question) should contain – natural language queries with examples. It goes beyond schema by showing how the question will be interpreted (routed to appropriate tools, used to fill arguments). However, it could be slightly more specific about the exact format or constraints (e.g., length limits).

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

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

The description clearly states the tool's purpose: it routes factual questions to 5,564 specialized tools across 1,462 sources, acting as a broad query dispatcher. It immediately distinguishes itself from web search and provides a specific, resource-rich verb 'Routes' paired with concrete examples like 'SEC filings, FDA drug data, FRED/BLS economic statistics'. The purpose is well-defined and distinct from siblings.

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

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

The description provides extensive guidance on when to use this tool versus alternatives. It explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', then gives clear step-up conditions for siblings (ask_pipeworx_grounded for grounded single answers, deep_research for multi-part queries, web search for breaking news). This is exceptionally thorough and actionable for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by explaining the beta nature, that it is a full working router, and that it falls back to nothing. It clarifies the experimental edge without contradicting annotations.

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

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

The description is informative and well-structured, front-loading the key identity (beta, identical router) and current state. It is slightly dense but each sentence adds value; could be trimmed slightly but remains clear.

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 (beta router with many tools, no output schema) and the presence of annotations, the description covers the experimental status, current equivalence, fallback, and usage comparison. It is sufficient for an agent to use the tool correctly, though it does not detail return format or error handling, which is acceptable given the context.

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

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

Schema description coverage is 100%, and the schema already describes all parameters (including aliases). The description does not add any parameter-specific meaning beyond what is in the schema, so it meets the baseline but does not exceed it.

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

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

The description clearly states it is a beta version of ask_pipeworx, identical in functionality and routing, but with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx and ask_pipeworx_grounded, making the purpose and scope specific and unambiguous.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It also explains the current state (no candidate active) and that it matches ask_pipeworx exactly, providing clear when-to-use guidance and implicit alternative (stable router).

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, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: details the internal routing, the extraction process ('EXTRACTS the answer using ONLY what the tool result contains'), the exact success/refusal output structure, and the extra cost. No contradictions with annotations.

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

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

Three concise paragraphs with front-loaded purpose, followed by routing, output format, and usage guidance. Every sentence earns its place—no fluff. The refusal reasons are listed compactly. Structure is logical and scannable.

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

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

Given the tool's complexity (6 aliases, no output schema, rich annotations), the description covers all necessary context: what the tool does, how it works, what it returns (both success and refusal), when to use it, and the trade-off vs. the sibling. Without an output schema, the explicit return structure is essential and provided.

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% (all six aliases for 'question' are documented). The description adds 'Your question in natural language' which is already clear from the schema. It does not add new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly specifying the verb (answer mode), resource (Pipeworx data), and distinguishing it from the sibling ask_pipeworx via the grounded extraction mechanism. It also mentions 'same routing as ask_pipeworx' to differentiate without 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 states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides a clear exclusion: 'prefer ask_pipeworx for casual lookups,' and quantifies the cost trade-off ('costs one extra LLM call'). This is model guideline clarity.

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 safe, read-only, idempotent behavior. The description adds extensive context: fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution-rule risk. 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?

Description is long but every sentence earns its place given the tool's complexity. Information is front-loaded with purpose and usage, then details. Could benefit from section breaks but overall well-structured.

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

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

Given no output schema, the description thoroughly covers response shapes, edge cases (closed markets, low confidence, wide spreads), and interpretation guidance. It prepares the agent for all common scenarios.

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

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

Schema coverage is 100% with clear descriptions. The description adds significant value by explaining how `market` accepts multiple formats, `depth` controls fan-out extent, and `include_raw` affects response size and use cases.

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 researches Polymarket bets by pulling Pipeworx data. Specifies inputs (slug, URL, question text) and distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on evidence and analysis.

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

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

Explicitly says 'Use for "should I bet on X"' and provides example queries. Though it doesn't directly exclude alternatives, the context of sibling tools and the detailed use cases make the tool's niche clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral context: data source (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, result sorting by primary metric, and return of 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 front-loaded with trigger phrases and is well-structured. While slightly verbose, every sentence adds value by explaining data sources, sorting, and efficiency gains. Minor redundancy could be trimmed, but overall earns its length.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations) and the presence of a good schema with annotations, the description covers all necessary aspects: use cases, data retrieval specifics, result formatting, and efficiency justification. No output schema, but return format is 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 coverage is 100% with both parameters described. Description significantly adds meaning: explains what each enum value retrieves (company vs drug data), provides example values (tickers/CIKs for company, names for drug), and specifies constraints (2-5 items). This goes well beyond the schema.

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

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

The description uses specific trigger phrases ('Compare X and Y', 'X vs Y') and clearly states the verb+resource: side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools like 'entity_profile' and explicitly contrasts with sequential single-pack lookups.

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

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

Provides explicit directive to prefer this tool over sequential lookups when comparing entities. Includes example queries that indicate when to use. Lacks explicit when-not scenarios, but the context is clear enough for correct 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 declare readOnlyHint, openWorldHint, idempotentHint. The description adds extensive behavioral detail: account requirements, free/paid tiers, parallel routing, findings packet with gaps[], contradictions[], hop field, citation_uri, semantic excerpting, expected duration (15-60s, thorough up to 90s), and limitation that topics not in catalog return empty gaps. 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 lengthy but densely packed with essential information. It front-loads the critical account requirement and fallback, then covers usage, behavioral details, and output format. Every sentence adds value, though some restructuring (e.g., grouping related details) could slightly improve 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?

Given the tool's complexity and no output schema, the description is remarkably thorough. It covers purpose, usage context (alternatives, account requirements, depth selection), behavior (parallel routing, gap recovery, contradictions, citation URIs, excerpting), parameter semantics, and output characteristics. It also sets expectations for response time and empty results when topics are out of scope.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra meaning: explains the depth enum (quick=3 facets, standard=3 with gap recovery+contradictions, thorough=6 with iterative hop+contradictions) and clarifies that thorough needs a paid plan. For the question parameter, it emphasizes broad/multi-part natural language. This adds value beyond the schema, but schema already provides basic descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources in one call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes this from siblings like ask_pipeworx (single lookup) and current-news use cases.

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

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

The description provides explicit guidance on when to use this tool vs ask_pipeworx (single lookup, breaking/current news) and which depth to choose. It also warns that a paid plan is needed for thorough depth and that users not signed in should use ask_pipeworx instead.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds valuable behavior: returns top-N most relevant tools with full schemas and curated examples, ready to call directly. This goes beyond annotations by detailing the output structure and usage pattern. 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?

Four sentences, each serving a purpose: purpose, domain list, output description, usage advice. Front-loaded with the verb. No wasted words. Structurally clear.

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 6 parameters, 33 siblings, and no output schema, the description covers the tool's role fully: it is a discovery tool that returns ready-to-use tool definitions. It tells the agent when to call it (FIRST) and what to expect. No gaps.

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

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

Schema coverage is 100% and schema descriptions are good. The description adds context: it explains that the top-N tools are returned, that results include schemas, and mentions aliases like 'task', 'q', 'search', 'description'. This helps the agent understand how parameters affect output.

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

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

The description starts with 'Find tools by describing the data or task' which is a clear verb+resource. It then lists numerous domains (SEC filings, financials, etc.), making the scope explicit. It distinguishes from sibling tools which are specific data functions, e.g., search_poems, by focusing on discovery.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear usage context but does not explicitly state when not to use it or list alternatives, though the sibling list implies it's the discovery entry point.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds specific behavioral details: it fans out across multiple data sources, returns specific fields, and notes the patents API sunset in May 2025 with soft-fail behavior. No contradictions.

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

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

The description is somewhat long but front-loaded with example queries and a clear purpose. Every sentence adds value, covering usage, data sources, return fields, and a caveat. It could be slightly more terse but remains 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?

No output schema, but the description enumerates all major return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and mentions limitations (patents sunset). This provides adequate completeness for an agent to 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% with descriptions for both parameters. The description adds example values and reinforces that names are not supported, but since the schema already adequately describes the parameters, the description provides only marginal additional meaning.

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

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

The description clearly states it provides a full cross-source profile of a US public company in one parallel call, with specific data items and examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from chaining multiple single-source lookups, making its purpose unambiguous.

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

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

It explicitly says to prefer this over chaining when a holistic view is requested and warns that names are not supported, directing users to use resolve_entity first. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description aligns with these but adds no new behavioral context beyond stating it deletes. Given annotations cover the safety profile, a 3 is appropriate.

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

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

The description is two sentences: first states purpose, second gives usage guidance and pairing. Every sentence adds value with no fluff.

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

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

For a simple destructive tool with one parameter and no output schema, the description alongside annotations and schema covers what, when, and pairing. It could mention return value behavior but is generally complete.

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

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

The input schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete.' The description does not add extra meaning like key format or constraints, so baseline 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory by key), and distinguishes from siblings like 'remember' and 'recall' which are for storing and retrieving.

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?

Description provides explicit use cases: when context is stale, task is done, or to clear sensitive data. It also suggests pairing with remember and recall. However, it does not explicitly mention when not to use 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 indicate read-only, idempotent, non-destructive behavior. The description adds process details (fetching, extracting, emitting) that align with annotations. It could be more explicit about lack of side effects, but overall good.

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 appropriately sized with three sentences that front-load the core purpose, then provide process and use cases. Each sentence is informative, though minor wordiness is present.

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

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

For a simple read-only tool with two parameters and no output schema, the description covers purpose, process, and use cases. It does not address error handling or fetch failures, but that is acceptable for its simplicity.

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

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

Schema coverage is 100% with parameter descriptions already present. The tool description does not add new meaning beyond restating the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, specifying the resource and output format. It distinguishes itself from siblings as no other tool generates llms.txt files.

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 lists specific use cases (client indexing, personal projects, competitor auditing) and provides clear context. However, it does not explicitly mention when not to use the tool or suggest 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?

Adds behavior beyond annotations: 'Returns full poem text (capped)' indicates truncation, and 'Keyless' indicates no auth required. No contradictions with annotations (readOnlyHint, etc.). Could mention pagination or rate limits but not critical given simplicity.

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

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

Two sentences, no unnecessary words, front-loads key information: full-text search, capped results, keyless. Highly concise and well-structured.

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

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

Adequate for a simple 2-parameter tool with no output schema. Explains core functionality and cap behavior. Could include error handling or timeouts but not essential. Annotations fill gaps on idempotency and read-only nature.

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

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

Schema description coverage is 100%, so parameters are well-documented in schema. Description adds minimal extra (e.g., 'Keyless' not param-related). Baseline score of 3 appropriate as description does not significantly enhance parameter understanding.

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

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

Clearly states it performs full-text search within poem lines on PoetryDB, identifying the specific verb (search), resource (poem lines), and scope (contains phrase). Distinguishes from sibling tools like 'search_poems' which likely search whole poems or metadata.

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?

Mentions 'Keyless' indicating no authentication needed. Implicitly guides usage for line-level search vs broader search. Does not explicitly state when not to use but provides adequate context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds 'Keyless', clarifying no authentication is needed, which is useful 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?

Two succinct sentences with no wasted words, front-loading the core purpose and a key behavioral trait.

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, parameterless listing tool with comprehensive annotations, the description fully covers what an agent needs: purpose and authentication status.

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 zero parameters and 100% schema coverage, no parameter details are needed. The description's 'Keyless' adds slight extra context, fitting the baseline of 4 for no-parameter tools.

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 lists all authors from PoetryDB with a specific verb 'List', making it distinct from other query tools like 'search_poems' or 'random_poems'.

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

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

The description implies usage for retrieving all authors without a key but does not explicitly state when to use this versus alternatives or provide 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, destructiveHint. Description adds that it returns specific fields but does not contradict annotations. No additional behavioral context needed.

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

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

Three sentences: purpose, return fields, usage guidance. Front-loaded, 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?

For a simple tool with 1 optional param and no output schema, description covers purpose, return fields, and usage. Complete.

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

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

Schema coverage 100% with parameter description. Description does not add parameter details beyond schema, but 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?

Clear verb 'List' and specific resource 'subscriptions'. Specifies it returns caller's active subscriptions and lists returned fields. Distinguishes from sibling tools like subscribe/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 states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This guides agent to use before subscribe/unsubscribe.

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

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

Annotations provide no useful hints (all false), so the description carries the burden. It discloses the claim_token flow (returns token without account, can be passed back to read status), daily rate limit, and that it's free/doesn't count against quota. No contradiction with annotations.

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

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

The description is dense but each sentence earns its place, covering purpose, usage, exclusions, token flow, and rate limits. It's front-loaded with the core purpose, but could be slightly more scannable with paragraph breaks; still, nothing is fluff.

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

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

Despite no output schema, the description fully explains the response behavior (claim_token retrieval). It covers all necessary context: what counts as valid feedback, filtering by scope, token mechanics, rate limits, and cost. Complete for a tool with only 4 optional params.

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 extra semantics: clarifies claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and instructs to describe issues in terms of Pipeworx tools/packs, which enriches the message parameter beyond schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from siblings like ask_pipeworx (querying) and subscribe (alerts), even scoping to 'tools served by this Pipeworx connection'.

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 enumerates when to use (bug, feature/data_gap, praise) and when not to use (different MCP server, telling the user to file elsewhere). It also provides practical guidance like 'Describe the issue in terms of Pipeworx tools/packs' and mentions rate limits, giving clear contextual triggers.

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?

Adds context beyond annotations: describes data source (CF analytics-engine), no PII, caching behavior (5min-1h), and return content (pack, tool, count). 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?

Efficient single paragraph with clear front-loading of purpose, followed by structured use cases and technical details. No superfluous 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?

Despite no output schema, description specifies return fields (top tools, packs, volume) and explains data source, caching, and parameter. Complete for a simple one-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 covers the single parameter fully; description adds minimal extra value with window selection guidance. Baseline 3 due to 100% coverage, raised to 4 for the additional context.

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

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

Description clearly states 'Returns the top tools, top packs, and total call volume' with a specific verb and resource, and differentiates from siblings by focusing on trending usage of Pipeworx 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?

Lists three explicit use cases and explains window trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), but does not explicitly exclude 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 indicate read-only, open-world, idempotent, non-destructive behavior. The description adds deep context: explains internal checks (Jaccard similarity >0.30, partition filter for placeholders, fill check against CLOB depth) and warns when not to trade. 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?

Description is lengthy but well-structured with clear paragraphs per mode. Some technical details could be tightened, but the complexity of the tool justifies the length. No wasted sentences, though some repetition of 'partition_check' concept.

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 explains the response structure (opportunities[], partition_check) and the fill check logic. It covers modes, edge cases (low similarity, placeholders), and references a sibling tool for custom sizing. Missing full details of every returned field, but sufficient for a complex arbitrage 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 covers both parameters with descriptions. The description adds substantial meaning beyond schema: explains format of event slug, what topic expects, how each mode works, and includes concrete examples. Despite 100% schema coverage, the added detail significantly aids agent understanding.

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

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

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes multiple modes (no args, event, topic) and provides examples, making the purpose specific and distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly tells when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Provides recommendations and even points to alternative tool ('For custom sizing use polymarket_fill_risk'). Clear when-not guidance.

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

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

The description extensively explains internal logic, including the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), edge calculation with slippage, Kelly fraction caps, and caching. It goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing the response structure, diagnostics, and constraints like 'placeholder-slug filter'. No contradictions with annotations.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the core purpose, then organized into logical segments (model families, knobs, response structure). The use of bullet points and clear sectioning makes it scannable. No filler or redundancy.

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

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

Given the tool's complexity (9 parameters, no output schema, nested objects), the description is remarkably complete. It explains the output structure (by_segment, fed_candidates, diagnostics), the meaning of each field like edge_pp_net, and how knobs affect results. The absence of an output schema is fully compensated by the description.

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?

All 9 parameters are documented in the input schema with descriptions (100% coverage), so the baseline is high. The description adds meaningful context beyond the schema, such as clarifying 'min_liquidity' as a tradeable-edge filter and explaining why 'min_partition_leg_kelly' is needed. This extra context justifies a score above the baseline.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb ('Scan') and resource ('Polymarket markets'). It explicitly targets the use case 'what should I bet on today', distinguishing it from generic market data tools. The purpose is specific and actionable.

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 ('what should I bet on today') and explains that Fed bets are excluded from ranking. However, it does not explicitly state when not to use this tool or compare it to alternatives like polymarket_arbitrage. The guidance is strong but lacks explicit 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?

The description adds significant detail beyond annotations: explains data source (daily snapshots), output structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, daily closes, not intraday), and computation of decay metrics. 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?

Description is densely informative but well-structured, front-loading purpose. Some verbosity in examples ('the median lifespan is your competition clock'), but overall efficient for the complexity.

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

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

Given no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and computation details. Covers limitations and edge cases (gaps in data). Fully meets the needs for a complex analytical 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?

Parameters are fully described in schema (100% coverage). Description adds defaults and constraints (e.g., 'default 14, max 30' for days, 'default 1wk' for window), providing additional clarity beyond schema alone.

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

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

The description clearly states 'Edge persistence and decay telemetry' answering a specific question about edge duration and decay. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current 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 implies when to use this tool by contrasting fresh vs. old edges, but it does not explicitly exclude alternatives or state when not to use it. Provides clear context without 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, openWorldHint, idempotentHint, and non-destructive. The description adds detailed return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains the check behavior for both modes, and highlights forced directional risk. 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 well-structured with clear sections for modes and return fields, but it is somewhat verbose. However, the complexity of the tool justifies the length, and every sentence serves a purpose.

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

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

Given the 4 parameters, no output schema, and no nested objects, the description thoroughly covers input semantics, return fields, and usage warnings for both modes. The verdict field gives error indication, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond the schema: clarifies size_usd semantics for single-market vs basket, explains side defaults, and describes how the tool walks the ladder. This adds actionable context for the agent.

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 ('realizable-vs-theoretical edge check against live CLOB order-book depth'). It clearly distinguishes two modes (single-market and basket) and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by directing when to use this tool.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns against partial fills converting an arb into unhedged direction and mentions that theoretical overround on thin books is not capturable, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already signal safety, but description adds substantial behavioral context: two modes, response structure (leg prices, spread, safety fields), and explains compatibility_warning causes (non-equivalent bet shapes, semantic mismatch). It also covers temporal_alignment and skipped counters. No contradiction with annotations; description complements them.

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

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

Description is lengthy but structured: starts with purpose, then modes, response, safety fields. Each sentence adds value; no filler. Could be slightly more compact but complexity warrants 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?

No output schema, but description covers response format (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment) and counters. For a 3-param tool with no required fields, this is fully adequate for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by explaining topic as pre-mapped macros with list and examples, and explicit parameters with examples. It links topic to auto-fetching behavior. Slightly above baseline due to depth.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket, with specific verb 'cross-venue spread' and resource 'the same resolving question'. It distinguishes from siblings by focusing on cross-venue comparison, not individual venue analysis.

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

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

Explicitly describes two modes (topic and explicit) and provides when-not-to-use guidance: the compatibility_warning indicates non-tradeable spreads. It warns that pre-mapped topics often return warnings, so users should not assume tradeability. Alternatives implied by specifying explicit pairing.

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, destructiveHint false. The description adds beyond by noting 'capped' poem text and 'Keyless' (no authentication needed), which provides useful behavioral context without contradicting annotations.

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

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

The description is extremely concise, using two short sentences that immediately convey purpose and key traits. No filler or redundant information.

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

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

Given the tool's simplicity (1 parameter, rich annotations, no output schema), the description adequately covers the return type (full poem text capped) and key trait (keyless). Could mention return structure or typical usage examples, but sufficient for its 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% (count parameter fully described). The description does not add additional meaning about the parameter beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action (Fetch), the resource (random public-domain poems from PoetryDB), and the return (full poem text, capped). It distinguishes from siblings like search_poems or get_poem_lines by specifying randomness and public-domain.

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 explicit guidance on when to use this tool versus alternatives. Siblings like search_poems and get_poem_lines exist, but no comparisons or exclusions are given. 'Keyless' hints at no auth, but lacks explicit context.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds behavioral detail: scoping per identifier, listing capability, and pairing with remember/forget, which is useful beyond annotations.

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

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

Two sentences, no wasted words. Front-loaded with the primary action. 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?

For a simple retrieval tool with one optional parameter and no output schema, the description is fully complete: what, when, scoping, pairing, and behavior of omitting key.

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 the key parameter fully. Description adds extra meaning: omitting key lists all, explains purpose of keys, and ties to memory system. Baseline 3, extra context justifies 4.

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

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

Clearly states it retrieves a saved value or lists all keys. Verb (retrieve/list) and resource (memory key) are specific. Distinguishes from sibling tools remember and forget.

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

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

Explicitly says when to use: to look up context stored earlier without re-deriving. Implies when not to use by mentioning paired tools. Provides scoping context.

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

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

The description discloses that setting mark_read:true modifies state (flags events as read), which contradicts the annotation readOnlyHint=true (declaring no side effects). This contradiction is a serious inconsistency, warranting a score of 1.

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, each serving a purpose: primary action, parameter guidance, and alternative access. 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?

For a read tool with 5 optional parameters and no output schema, the description covers return content, filtering, side effects, polling suitability, and alternative access. It is fully self-contained.

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

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

The input schema covers all 5 parameters with descriptions. The description adds behavioral context for mark_read (affecting subsequent calls) and clarifies filtering semantics, going slightly 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 'Pull fired events from your subscription feed' with specific details on return fields (source, citation_uri, payload) and filtering options (type, since). This distinguishes it from sibling tools that handle other tasks.

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 (polling) and provides an alternative ('GET registry.pipeworx.io/alerts.json for scripts and dashboards'). It also clarifies how to use parameters (e.g., mark_read for progressive fetching). However, it does not explicitly exclude specific scenarios or compare with siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description goes beyond by detailing the tool fans out to SEC EDGAR, GDELT/GNews (with fallback logic), and USPTO (soft-fail). It also outlines return structure (grouped changes, total count, 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 dense and front-loaded with query examples, then efficiently covers sources, fallbacks, and return format. A few sentences could be slightly more terse, but overall 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 complexity of multiple sources (SEC, GDELT/GNews, USPTO) and lack of output schema, the description is remarkably complete. It covers input formats, source behavior, fallback logic, soft-fail for patents, and return structure (changes grouped by source, total count, citation URIs).

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. The description adds value by explaining the 'since' parameter accepts relative shorthand with examples (e.g., '30d', '3m'), noting that 'type' is constrained to 'company', and clarifying that 'value' can be a ticker or CIK. Provides guidance on typical usage ('30d' or '1m' for monitoring).

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 (SEC filings, news, patents) in a time window. It distinguishes from sibling 'entity_profile' by specifying that this tool is for dynamic updates, not 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?

Explicitly gives example queries ('What's new with X'), explains input formats (ISO date or relative shorthand), and advises when to use the sibling 'entity_profile' instead. Also describes fallback behavior between news sources.

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 behavioral context: storage scoped by identifier, persistence differences between authenticated (persistent) and anonymous (24 hours) sessions. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with purpose. It is clear and efficient, though slightly longer than strictly necessary. No redundant information.

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

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

Given two simple parameters, no output schema, and comprehensive annotations, the description covers all necessary aspects: purpose, usage, scope, persistence, and pairing with siblings. No notable 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 description coverage is 100%, so baseline is 3. The description gives examples of keys and values but does not add significant meaning beyond the schema's descriptions. Minimal extra 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 uses the specific verb 'save' and resource 'data', and explicitly distinguishes from siblings 'recall' and 'forget' by stating to pair with them. It also specifies the scope (across conversations or sessions), which differentiates it clearly.

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

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

The description explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It provides concrete examples (resolved ticker, target address, etc.) and mentions complementary tools (recall/forget), giving clear usage context.

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

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

Annotations already declare readOnly, openWorld, and idempotent, and the description adds rich behavioral context: identifiers are labelled with source, unresolved identifiers are explicitly stated under 'unresolved' rather than omitted, and LEI/FIGI enrichment degrades gracefully if external services fail. 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?

Though lengthy, every sentence serves a purpose—example queries, supported types, source labelling, unresolved handling, graceful degradation, and internal cascading. It is front-loaded with user intents and logically structured, so the length is justified.

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

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

Given the tool's complexity and lack of output schema, the description covers return format (labelled identifiers, unresolved field), input variants, edge cases (external API failure), and internal behavior (cascading lookups). It provides complete guidance for correct invocation.

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

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

Schema coverage is 100%, and the description goes far beyond it. For 'company' it explains the cross-source identity spine (CIK, ticker, LEI, FIGI), ISIN-to-LEI mapping, and fallback behavior; for 'drug' it specifies RxCUI, ingredient, brand, and citation. This adds deep semantic meaning the schema lacks.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists supported types and example queries, clearly distinguishing it from siblings like entity_profile or compare_entities by positioning it as the first-step name-to-ID tool.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID,' giving direct precedence over alternatives. It also explains that it replaces 2-3 manual lookups, clarifying the intended context and value.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific metrics (score, confidence, signal density). It also clarifies the subject/competitor distinction.

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 remarkably concise at three sentences, with the core purpose front-loaded. Every sentence adds value: purpose, mechanism, and use case. No redundant or 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?

Given no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density). It explains the process and context. It could mention potential external API calls or timeouts, but overall it's sufficient for a comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema's descriptions of parameters. It reinforces the role of 'entities' but doesn't provide additional guidance on 'models', '_apiKey', or 'context'.

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

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

The description clearly states the tool's action: 'Compare AI visibility across multiple entities side-by-side' using a specific verb and resource. It distinguishes itself from the sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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 context: 'Useful for competitive AI-marketing audits' with a concrete example. While it doesn't state when not to use or directly name alternatives, the purpose strongly implies when this tool is appropriate over single-entity checks.

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

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

Annotations provide readOnlyHint, etc., but the description adds behavioral traits beyond: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists if it times out. This gives useful behavioral expectations beyond what annotations convey.

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

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

The description is dense but front-loaded with the main purpose and then details. Every sentence adds value, though it could be slightly more concise. It wastes no words and is 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?

There is no output schema, but the description explicitly lists the return fields: summary block (is_latest, license, etc.), per-advisory detail, links, and alternative versions. It also covers partial failure behavior. The description is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the description adds minimal meaning beyond the schema. Both parameters (package, version) are fully described in the schema; the description only reiterates that scoped packages are accepted and version defaults to latest. Thus 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 is a composite check for adding npm packages, fanning out to deps.dev and bundlephobia for license, advisories, and bundle size. It specifies the exact resource (npm package) and scope. Among siblings (poems, polymarket, etc.), it is distinct and unambiguous.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives when-not: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This provides clear guidance on when to use and when to use 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 read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it returns full text, author, line count, and notes the limitation 'searches titles only, not poem body text.' No contradictions with annotations.

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

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

Two sentences, immediately stating action and scope. No filler. Front-loaded with the verb 'Search' and resource 'PoetryDB'. Highly 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?

Given no output schema, description partially compensates by listing return fields. However, it omits default limit, pagination, and how the author parameter combines with title. These gaps reduce completeness for a search 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 covers all 3 parameters with descriptions, so baseline is 3. The description provides a usage example ('The Road Not Taken') but does not add new parameter info beyond the schema. The interplay between title and author is not explained.

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 searches poems by title or partial title and returns specific fields. It distinguishes from sibling tools like get_poem_lines and list_authors, but does not explicitly mention the author parameter, which could cause 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 implies usage when searching by title but does not explicitly state when to prefer this tool over alternatives like get_poem_lines or when not to use it (e.g., for full-text search). No exclusions are given.

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 as false. The description adds critical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and that passages carry offsets for verification.

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

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

The description is concise, consisting of three sentences: the first states the core function, the second explains when to use it and its benefits, and the third provides technical details. Every sentence is essential and well-organized.

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 return format (top-N passages with character offsets and similarity scores), the truncation behavior, and the pairing with ask_pipeworx_grounded. This covers all needed context for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing example queries for the query parameter (e.g., 'supply-chain risk') and clarifying that text is 'the document text to search inside', which matches schema but adds context. This slight additional guidance warrants a 4.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the verb 'search', the resource 'inside a record', and the scope 'top-N passages with character offsets and similarity scores'. It distinguishes itself from the sibling ask_pipeworx_grounded by explaining how they pair.

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 when the record is too big to cram into the prompt' and explains that it saves context and returns only relevant passages. It also mentions pairing with ask_pipeworx_grounded, providing a clear alternative for grounded answers.

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 non-read, open-world, idempotent, non-destructive. Description adds OAuth requirement, return value, delivery channel behaviors (SMS cap, webhook auto-disable, HMAC signing), all beyond annotations. 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?

Dense single paragraph with good front-loading of purpose and type list. Could benefit from bullet points or clearer structure, but no wasted 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?

Covers purpose, parameters, delivery channels, constraints, prerequisites, and return value. No output schema needed since description mentions 'returns the new subscription id'.

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 100% (baseline 3). Description adds extensive details: enum explanations for 'type', type-specific examples for 'params', and full delivery channel semantics including constraints and verification steps.

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 'create' and resource 'subscription' to a live-data event stream, returns new subscription id. Distinguishes from sibling tools like 'list_subscriptions' 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?

Specifies when to use (creating subscriptions), lists prerequisites (OAuth account, phone verification for SMS), and details supported types with examples. Lacks explicit exclusions or comparisons with alternatives like 'recent_alerts'.

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 the tool is read-only, idempotent, and non-destructive. The description adds that it returns category-bucketed example questions with exact tool argument shapes, and explains the behavior difference between no arguments and a topic filter. 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 a single paragraph but efficiently conveys aliases, purpose, output, and usage. Every sentence adds value, though bullet points could improve scannability. Still, it is well-structured and not verbose.

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

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

For a tool with only one optional parameter and no output schema, the description is remarkably complete. It covers when to use, what it returns, how to customize, and how it fits into the overall onboarding flow.

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 one optional parameter. The description provides a full list of valid topic values (e.g., finance, pharma, economics) and explains that omitting it yields a cross-category spread, significantly enriching the schema's 'string' 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?

The description clearly specifies the tool is for onboarding new users, providing example questions categorized by topic. It distinguishes itself from siblings by positioning as the first tool to use when unfamiliar with Pipeworx's capabilities.

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 to use this tool FIRST when the user doesn't know what Pipeworx can do, and explains how to call with no arguments vs. a specific topic. Could mention alternatives like discover_tools more directly, but the guidance is clear and context-rich.

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 adds key context beyond annotations: row is deactivated (not deleted), historical events remain, and ownership is enforced. Aligns with annotations.

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

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

Three short, focused sentences. Front-loaded with action and target. No wasted words.

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

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

Simple 1-param tool with no output schema; description fully covers purpose, effect, ownership, and relation to sibling tools (recent_alerts).

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 the single parameter with description (100% coverage). Description adds no extra detail beyond referencing the id.

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 'Cancel' and resource 'subscription by id', clearly distinguishing from siblings like subscribe and list_subscriptions.

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

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

States ownership enforcement and that only own subscriptions can be canceled, implicitly guiding usage. Could be more explicit about 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?

Rich behavioral detail beyond annotations: the two-path execution model, the distinction between could_not_verify and unsupported, the presence of verification_error{stage,detail}, and the return of verbatim evidence with pipeworx:// citations. It also clarifies that could_not_verify is not evidence for/against, which is critical for correct agent usage. No contradiction with readOnlyHint=true.

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

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

Dense but efficient: trigger phrases, use case, dual-path logic, return value summary, critical caller warning, and efficiency justification. Every sentence adds value; no filler.

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

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

Even without an output schema, the description explains required return fields (verdict, actual value, citation, reasoning), distinguishes error vs. unsupported states, and specifies the two processing paths. This is a complete mental model for an agent to decide 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 already covers 100% of parameters with detailed descriptions and examples. The description adds the context of 'exact percent-delta math' and mentions tolerance override, but these are also captured in the schema. Description does not significantly enhance parameter understanding beyond the schema.

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

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

The description opens with explicit trigger phrases and a clear verb+resource: 'natural-language claim verification against authoritative sources.' It immediately distinguishes itself from siblings by stating it replaces 4–6 sequential calls and by detailing the specialized SEC EDGAR fast path for financial claims.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides clear routing guidance (financial vs. other claims) and warns about misinterpreting could_not_verify. It doesn't name alternative tools for non-claim tasks, but given the sibling list includes other research tools, the usage context is clear enough.

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