Github

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context: cost implications for using Anthropic (BYO key), which model is the default free one, and the structure of return values. 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 concise and front-loaded with the primary action. It uses a single paragraph with efficient sentences, no redundancy, and covers all key aspects without being 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?

The description is complete for a tool with moderate complexity. It explains the scoring mechanism, return format (including per-model fields), default model, and optional key usage. Without an output schema, it adequately describes the output structure.

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 extra meaning by explaining that _apiKey is only needed for 'anthropic' model, that context helps disambiguate, and that models can be specified to probe. This goes beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility. It uses specific verbs ('Probe', 'score') and identifies the resource (LLMs). The description sets it apart from sibling tools by focusing on AI visibility measurement.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and gives context for when to use the optional _apiKey parameter. It does not explicitly list when not to use or compare to siblings, but the context is sufficient.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it routes questions to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotations to explain how the tool operates internally, providing full transparency.

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

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

The description is front-loaded with the key 'prefer over web search' directive and use cases. It is relatively long but every sentence serves a purpose: listing domains, examples, and step-up options. Minor redundancy (e.g., examples repeated in schema) but overall efficient for a complex tool. Could be slightly tighter, but still strong.

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 parameters, no output schema), the description is comprehensive. It covers what the tool does, when to use it, how it works internally (routing, filling args, citations), and provides ample examples. Without an output schema, the description effectively explains what the user gets: a structured answer with stable URIs. No gaps remain.

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

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

The input schema has 100% description coverage, listing the 'question' parameter and several aliases (q, text, etc.). The description reinforces this by explaining that the tool accepts natural language and gives examples, adding value beyond the schema. However, it doesn't elaborate on format or constraints beyond what schema provides, so it's slightly above the baseline of 3.

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

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

The description clearly identifies ask_pipeworx as a question-routing tool that pulls from 4,774 tools across 1,242 sources for authoritative structured data with citations. It lists diverse domains (SEC, FDA, FRED, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

The description explicitly states 'PREFER OVER WEB SEARCH' and provides concrete examples of when to use it (e.g., 'what is', 'look up', 'current US unemployment rate'). It also gives clear guidance on when to step up to alternatives: ask_pipeworx_grounded for verbatim evidence and confidence, deep_research for multi-part questions, and suggests web search for breaking news. This makes usage boundaries very clear.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds valuable behavioral details: it returns structured response with fields like answer, evidence, confidence, source, fetched_at, and refusal reasons. It also mentions an extra LLM call cost and that it picks from 4,774 tools across 1242 sources. 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?

The description is well-structured with a clear first sentence stating purpose, followed by details on routing, response format, and usage guidance. While it is somewhat long, every sentence provides essential information without redundancy.

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

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

Given the tool's complexity (routing, extraction, refusal handling), the description covers purpose, behavior, output format, when to use, cost, alternatives, and refusal reasons. No output schema exists, so the description fully compensates.

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 6 parameters are aliases for the question, and the schema provides descriptions for each. The description merely states 'Your question in natural language,' which adds little beyond the schema. With 100% schema description coverage, baseline is 3.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies the action (extracts answer using only tool result) and distinguishes itself from the sibling ask_pipeworx by noting it costs an extra LLM call and is for high-stakes reads.

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

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

The description explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also says 'prefer ask_pipeworx for casual lookups,' providing clear guidance on alternatives.

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

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

The description extensively discloses behavioral traits beyond the annotations: it explains the resolving, classifying, and fan-out processes; safety mechanisms (low-confidence short-circuit, closed-market handling, wide-spread detection); resolution-rule risk; and response shapes. There is no contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all consistent).

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

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

The description is long but well-structured with sections (classifiers, fan-out examples, response shapes, safety). It is front-loaded with the main purpose. Every sentence adds value given the tool's complexity. However, it could be slightly more concise without losing essential details.

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

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

Despite lacking an output schema, the description thoroughly covers what the tool returns, including edge cases like low-confidence matches, closed markets, wide spreads, cancellation rules, and parent events. It 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 coverage is 100%, so baseline is 3. The description adds value by explaining the market parameter accepts slug, URL, or question text; describes the depth enum (quick vs thorough); and clarifies the include_raw default and its trade-offs. This extra context justifies a score of 4.

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

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

The description clearly states the tool's purpose: researching Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output components (evidence packet, market-vs-model comparison). Although it doesn't explicitly differentiate from sibling tools, the usage examples ('should I bet on X') make the intent unmistakable.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also gives classifier examples and fan-out examples. However, it does not explicitly state when NOT to use or list alternatives from siblings, which would improve the score.

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

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

Annotations declare read-only, idempotent, non-destructive. Description adds context: pulls from SEC EDGAR/XBRL for companies (with off-calendar handling) and FAERS for drugs, returns sorted results with 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?

Front-loaded with common query patterns, then dense with useful details. Each sentence adds value, though could be slightly more streamlined.

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 return value: paired data + citation URIs, sorted by primary metric. Sufficient for the tool's complexity and entity types.

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 clearly described. Description adds meaning beyond schema by explaining what data each type retrieves and the format of values (tickers/CIKs, drug names).

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 common query phrases, then clearly states it does side-by-side comparison of 2-5 companies or drugs in one parallel call. It specifies data sources and distinguishes from siblings like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and mentions it replaces 8-15 sequential lookups, providing clear guidance on when to use it.

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

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

Discloses account requirement, depth behavior, return format (findings packet with gaps), and expected latency (15-60s). 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 detailed but front-loaded with key facts; every sentence adds value, though could be slightly more concise.

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

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

Given complexity and no output schema, description fully explains behavior, prerequisites, return format, and latency, making it complete for agent understanding.

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

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

Schema coverage is 100%, and description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8) and that question accepts natural language, though param details are already covered.

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

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

The description clearly states it performs grounded multi-source research across structured data sources, distinguishes from siblings like ask_pipeworx, and specifies that it is not open-web search.

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

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

Explicitly provides when to use (broad/multi-part questions over structured data) and when not to (single lookup, breaking news), with specific alternative tools named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns top-N most relevant tools with full schemas and examples, and states that results are 'ready to call directly, no second schema lookup needed'. 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 fairly concise and front-loaded with the core purpose. Every sentence earns its place: domains list, output format, usage guidance. Minor redundancy in listing aliases again, but overall efficient.

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

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

Given the tool's complexity and lack of output schema, the description sufficiently explains what is returned (names, descriptions, full schemas with examples). It also provides usage context relative to many sibling tools. Schema includes examples. 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 description coverage is 100%, so baseline is 3. The description does not add significant parameter-level meaning beyond what the schema already provides (aliases are already documented in schema). It mentions 'top-N' but that's a behavioral output, not parameter semantics.

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

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

The description clearly states the tool's purpose: to find tools by describing data or task. It lists many specific domains (SEC filings, FDA drugs, etc.) and uses verbs like 'browse, search, look up, or discover', making it distinct from sibling tools that operate on data rather than discovering tools themselves.

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)'. This provides clear when-to-use guidance and implies when not to use it (when you already know which tool to call).

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description details the tool's behavior: fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), lists exact return fields (cik, recent_filings with URIs, fundamentals sorted, patents with a soft-fail note, news via GDELT→GNews fallback, LEI). It also discloses the USPTO PatentsView API sunset limitation, which is crucial for understanding potential failures. No contradiction with annotations.

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

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

The description is front-loaded with examples and a clear one-sentence summary, but becomes somewhat lengthy listing all return fields. While each detail is useful, brevity could be improved. However, the structured listing of return fields is well-organized and easy to parse.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description is comprehensive: explains what is returned, how data is sourced, and notes a known failure mode (USPTO sunset). Missing details like error handling or rate limits would be ideal but are not critical for typical agent use. The description is complete enough 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?

Input schema already covers both parameters with enum and description (100% coverage). The description adds value by clarifying usage: type must be 'company', value must be ticker or zero-padded CIK (with examples), and explicitly notes that names are not supported. This goes beyond schema descriptions and helps avoid common mistakes.

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 natural language examples like 'Tell me about X' and 'company profile for Microsoft', immediately clarifying the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It clearly distinguishes from sibling tools by emphasizing parallel execution vs chaining, and specifies the resource type (US public company) and action (profile).

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing clear when-to-use guidance. Also explains when NOT to use: 'names not supported (use resolve_entity first if you only have a name)', directing the agent to an alternative tool. This covers both usage context and 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 destructiveHint=true and idempotentHint=true, and the description adds the context of clearing sensitive data. However, it doesn't mention behavior when key doesn't exist (e.g., error vs no-op), which would be helpful.

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

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

Two sentences, front-loaded with the action, followed by usage guidance. 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 tool's simplicity (1 param, no output schema), the description fully covers purpose, usage context, and sibling relationships. 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% with a single parameter 'key' described as 'Memory key to delete'. The description adds minimal extra meaning beyond the schema.

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

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

Clearly specifies 'Delete a previously stored memory by key' – a specific verb and resource, distinguishing it from related tools like remember and recall.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also names alternative tools (remember, recall) for 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?

Annotation indicates readOnly, openWorld, idempotent, non-destructive. Description adds behavioral detail: fetches page, extracts title/description/key links, emits markdown. No contradiction.

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

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

Three sentences: purpose, behavior, use cases. Front-loaded and efficient 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?

Complete for a simple tool with 2 params (one optional), annotations present, no output schema needed. Description explains output format sufficiently.

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; description rephrases schema for url and max_links but adds an example for url. No significant extra meaning beyond schema.

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

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

The description specifies the verb 'generate', resource 'llms.txt file for any URL', and distinct purpose from siblings. It clearly states what the tool does and the format of output.

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

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

Provides clear use cases (client site indexing, personal projects, competitor auditing) but does not explicitly mention when not to use or alternatives. However, sibling tools do not overlap, so context is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: public-only access, size cap of ~60k, and return format (decoded text vs directory listing with {name, path, type, size}). 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 a single, dense paragraph that front-loads the main action. Every sentence adds value - purpose, usage context, parameter details, and return format. No unnecessary words.

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

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

For a 4-param, 2-required tool with no output schema, the description covers everything: purpose, parameter roles, usage guidance, return format, size limits, and access restrictions. 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?

Schema coverage is 100% with descriptions. The description adds meaning by clarifying that omitting path or passing '' lists root, and that ref defaults to default branch. This adds practical context 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 starts with a specific verb and resource: 'Read a file from a PUBLIC GitHub repository (or list a directory) by path.' It clearly states the action and scope, and distinguishes from sibling tools by explicitly saying 'PREFER OVER WEB SEARCH' for file-reading queries.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH') and explains parameter behavior in detail (omit path for root, optional ref). It gives concrete examples and clarifies the tool's preferred use cases.

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

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

Annotations already declare safe read-only behavior. Description adds specifics: returns latest stable release with fields, includes recent releases, and fallback to tags. 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, front-loaded with purpose. Every sentence adds value. No redundancy.

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

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

For a simple tool with 3 parameters and thorough annotations, the description covers all necessary context: use case, return data, reliable fallback behavior.

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

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

Schema covers 100% of parameters with descriptions. Description adds no new parameter details beyond schema but explains overall behavior (fallback to tags) which indirectly aids 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?

Describes specific verb+resource ('Get releases') and distinguishes from siblings like list_commits or search_repos. Explicitly states it answers queries like 'what is the latest version of <project>'.

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

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

Provides clear usage context: 'canonical way to answer...' and mentions fallback to tags. Does not explicitly list exclusions or alternatives, but context is sufficient.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds specific return fields (description, stars, forks, etc.), 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 sentences, front-loaded with purpose, efficient. 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 read-only tool with output schema and detailed annotations, the description is complete enough. Could mention potential prerequisites like authentication, but not critical.

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 well-described. The description adds examples but not additional meaning beyond what the schema provides.

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

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

The description clearly states it gets full details for a specific repository, listing key return fields. It distinguishes from sibling tools like search_repos which is for searching.

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

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

Provides clear usage with examples and implies when to use (for a known repo). Lacks explicit when-not or alternatives, but context is sufficient.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by detailing the public nature of the data and listing return fields, but does not cover rate limits or authentication requirements.

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, using minimal words to convey purpose, return fields, and usage example. Every sentence is necessary and 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 the low complexity, single parameter, full schema coverage, and presence of an output schema, the description is complete. It covers all needed aspects for correct invocation.

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

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

The input schema has 100% coverage with a clear description and example for the single parameter. The tool description adds no additional semantic information beyond what the schema already provides.

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

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

The description clearly states the verb 'Get' and resource 'a GitHub user's public profile info'. It lists specific returned fields (name, bio, etc.), distinguishing it from sibling tools like get_repo or search_repos.

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 implicitly guides usage by requiring a username and providing examples (torvalds, gvanrossum). However, it does not explicitly state when to use this tool versus alternatives, though the context makes it clear for user profile lookups.

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 destructiveHint false, so the agent knows it's a safe read. The description adds value by specifying the output fields (sha, message, author, date) and explaining how parameters like sha, path, since/until affect results.

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

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

The description is concise with three sentences: purpose, usage guidelines, and parameter explanation. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description covers what the tool does, when to use it, parameter effects, and return fields. For a read-only list tool with 7 parameters (2 required), this provides sufficient context for correct invocation.

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

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

Schema coverage is 100% with per-parameter descriptions. The tool description adds meaning by grouping parameters (e.g., 'Optional sha (branch/tag/commit to start history from), path (only commits touching that file/dir), and since/until ISO timestamps') and mentioning per_page default and max, which the schema also covers but description reinforces.

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 lists recent commits on a repository to see latest activity, changes, and author. It distinguishes itself from sibling tools like search_code or get_file_contents by focusing specifically on commit history.

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 'PREFER OVER WEB SEARCH' for specific queries, providing clear when-to-use guidance. However, it does not mention when alternative tools (e.g., get_repo, search_code) might be better, but the given context is strong.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral details: it automatically filters out pull requests and lists the specific fields returned (number, title, state, labels, author, comment count, URL, timestamps). No contradictions with annotations.

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

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

Two sentences, front-loaded with the main action, no wasted words. Every phrase adds value: action, PR filtering, return fields, and default state. Ideal conciseness for a tool description.

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

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

Given the tool has 4 parameters, rich annotations, and an output schema, the description covers the essential aspects: action, default, filtering, and return content. It lacks mention of pagination limits or error conditions, but these are handled by schema and annotations, making the description sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description 'Defaults to open issues' repeats schema info, and 'filters pull requests out automatically' is behavioral, not parameter-specific. No additional parameter meaning is added beyond what the schema provides.

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

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

The description clearly states 'List issues for a GitHub repository by owner and repo name', specifying the verb and resource. It also distinguishes from siblings like list_commits and search_repos by focusing on issues and automatically filtering out pull requests, leaving no ambiguity about the tool's purpose.

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

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

The description implies usage context (to list issues for a repository) but does not explicitly state when to use this tool versus alternatives like search_repos. It lacks guidance on when not to use it or prerequisites, such as needing repository access.

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

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

Annotations already declare readOnly and idempotent hints. Description adds value by listing the returned fields (id, type, params, created_at, last_fired_at, fire_count), which the annotations do not cover. No contradictions.

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

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

Two sentences, no fluff. The first sentence states the core function, and the second provides usage context. Efficient and front-loaded.

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

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

For a simple list tool with one optional parameter, the description covers the return fields and usage scenario. It is complete enough for the agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and the description does not add additional context for the 'include_inactive' parameter. The baseline score of 3 is appropriate as the schema already fully describes 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?

Description uses specific verb 'list' and resource 'subscriptions', clearly stating the action. Does not explicitly differentiate from sibling tools like 'subscribe' or 'unsubscribe', but the purpose is unambiguous.

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

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

Provides guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool, but does not mention when not to use it or alternative tools.

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

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

Description goes beyond annotations by stating the feedback is free, does not count against tool-call quota, is rate-limited, and that the team reads digests daily with roadmap impact. 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 concise (5 sentences) and front-loaded with key information. Every sentence adds value—purpose, when to use, how to write, rate limits, and quota policy.

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, the description covers all necessary aspects: purpose, usage context, writing guidelines, rate limits, and quota. No output schema is needed, and context is fully 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 coverage is 100%, so baseline is 3. Description adds value by clarifying how to write the message (be specific, don't paste user prompt) and explains enum values in more natural language.

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

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

The description explicitly states the tool is for sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs and resources, and clearly distinguishes from sibling tools (e.g., research/query tools).

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

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

The description provides clear when-to-use guidance for each feedback type (bug, feature, data_gap, praise) and mentions rate limits (5 per identifier per day). It does not explicitly state when not to use, but context makes it obvious.

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 important behavioral context beyond annotations: self-aggregating signal from CF analytics-engine, no PII, caching details. Consistently aligns with readOnlyHint and destructiveHint=false.

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

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

Concise and front-loaded; every sentence adds value without fluff. Key info is presented efficiently.

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 and absence of output schema, the description adequately explains return values (top tools, packs, volume), caching, and data source. No missing info.

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

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

The schema already describes the parameter fully (100% coverage). The description reinforces the window durations and adds use-case context, providing additional value.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It uses specific verbs and resources, and distinguishes from siblings like discover_tools by focusing on trending data.

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

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

Explicitly provides three use cases for when to use the tool, giving context for its utility. However, it does not state when not to use it or mention alternatives, though the purpose implies scenarios.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds extensive behavioral details: walks child markets, checks ordering, computes partition checks, applies Jaccard similarity filter, partition filter, and fill check. 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?

Well-structured with clear headings (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value; length is justified given complexity. No waste.

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

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

Despite no output schema, description explains return structure: opportunities array with fields, partition_check object, and fill check details. Covers all necessary elements for a complex arbitrage detection 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, but the description adds meaning: explains event parameter triggers partition_check with date-axis/threshold-axis ordering, and topic parameter uses cross-event scanning with similarity filter. Adds context beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args trending scan, event mode, topic mode) from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly explains when to use each mode: no args for trending scan, event for per-event partition_check, topic for cross-event scan. Recommends event for specific markets and notes cross-event catches patterns single-event misses.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds detailed behavioral context: explains the three model families with formulas and data sources (e.g., 'lognormal barrier from 90d FRED log-returns'), output structure with diagnostics, caching at KV level keyed on knobs, and how filters affect results. This goes well beyond what annotations provide.

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

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

The description is very long (~500 words) and includes many technical details. While it is structured with numbered sections and front-loaded with the purpose sentence, it is not concise. The verbosity reduces readability for an agent. A more streamlined version could convey the same information more efficiently.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure: 'by_segment', 'fed_candidates/fed_note', and '_diagnostics' with examples and edge cases (e.g., empty segments). It covers filter behavior and caching. However, it does not provide a complete field list or exhaustive return type, so it is not a 5.

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

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

Input schema has 100% coverage with descriptions for all 9 parameters, so baseline is 3. The description adds extra context for key parameters: e.g., 'min_partition_leg_kelly' clarifies it applies per-leg inside partitions, and 'slippage_pp' gives reasoning about Polymarket trading fees. This additional explanation justifies a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets) and action (scan and return). While it does not explicitly differentiate from sibling tools like 'polymarket_arbitrage', it is distinct enough to avoid confusion. The phrase 'Built for "what should I bet on today"' provides context.

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 usage context: 'agents discover opportunities without paging hundreds of markets' and explains the three model families and applicable filters. It gives guidance on knob settings (e.g., 'min_liquidity', 'max_spread_pp') and their effects. However, it lacks explicit 'when not to use' or direct references to alternative tools, so it falls short of a 5.

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

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

Exceeds annotations by detailing response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, daily closes). Annotations already indicate safe, idempotent behavior; description adds rich behavioral context.

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

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

Front-loaded with core purpose and structured into sections (RESPONSE:). Slightly long but each sentence adds value for an agent needing detail.

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

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

No output schema exists, so description fully explains return values and limitations. Covers all necessary context for an agent to use the tool without additional references.

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

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

Schema coverage is 100%, so baseline is 3. Description adds only marginal value (defaults and 'snapshot family') beyond the schema's parameter 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 provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from siblings like polymarket_edges by focusing on historical tracking across snapshots.

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 assessing edge quality over time (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when to use this tool versus alternatives or exclude contexts.

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

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

Discloses behavioral details beyond annotations: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict (clean|degraded|cannot_fill); for baskets, it returns theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk. It explains that theoretical overround on thin books is not capturable, which goes beyond the readOnlyHint and idempotentHint 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 (mode selection, single-market details, basket details, usage guidance) and front-loaded with the core purpose. However, it is quite verbose; some sentences could be tightened without losing meaning. Every sentence earns its place, but brevity could be improved slightly.

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

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

Despite no output schema, the description thoroughly explains all return fields and verdicts for both modes. It covers the risk of forced directional risk and why partial basket fills are dangerous. For a complex tool with two modes and many outputs, this description provides complete context for an AI agent to understand what the tool does and what it returns.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the difference between single-market and basket modes for 'side' and 'size_usd', default behaviors, and the clamp range for size_usd. For baskets, it clarifies that size_usd is settlement notional (shares per leg). This provides context that the schema alone does not.

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 a 'realizable-vs-theoretical edge check' against live order-book depth for Polymarket, with explicit differentiation between single-market and basket modes. The verb 'check' and resource 'CLOB order-book depth' are specific, and it distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by explaining when to use it before those tools.

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

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

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It provides clear conditions for usage and explains the consequences of not using it (partial basket fills converting arb into unhedged directional position, the dominant loss mode).

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. The description adds extensive behavioral context: two modes, response structure (leg-by-leg prices, top_spreads_pp), and safety fields (compatibility_warning, temporal_alignment, skipped_cross counters). It explains when spreads are mathematically meaningless (temporal misalignment, non-equivalent bet shapes). 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 fairly long but well-structured: definition, modes, response, safety fields. All sentences are informative. Minor redundancy, but overall efficient.

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

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

No output schema, so the description must explain return values. It does so comprehensively: leg-by-leg prices, matched spreads, and safety fields. It covers temporal alignment and compatibility warnings. It even advises on rarity of real spreads. 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 coverage is 100%, so baseline is 3. The description adds value by listing the 10 topic shortcuts, explaining that explicit parameters override the topic-mapped side, and giving examples. This goes beyond the schema descriptions.

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

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

The description clearly states the tool calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and describes the output. It distinguishes this from siblings like polymarket_arbitrage by being cross-venue.

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 two modes and warns that pre-mapped topics often return compatibility warnings, implying when to use explicit mode. It mentions that real spreads are rarer than the list suggests, giving context. However, it doesn't explicitly state when not to use the tool or compare to alternatives beyond the sibling list.

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 value by stating scoping to identifier and lifecycle pairing, complementing structured data 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 cover action, usage, scope, and pairing. Every sentence contributes; 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 read tool with one optional parameter, the description covers purpose, usage, scoping, and relationships. Annotations handle safety; no output schema needed.

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

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

Schema coverage is 100% with one parameter well-described. Description reiterates usage ('omit the key argument') and adds context about listing all keys, but does not significantly enrich 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 clearly states the tool retrieves values saved via 'remember' or lists all keys, using specific verb 'retrieve' and resource 'value'. It 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 states when to use (look up stored context) and when to omit key (list all). Mentions alternative tools 'remember' and 'forget' for pairing, providing clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true. The description adds valuable behavioral context: explaining the effect of mark_read (flags events read so next call only shows newer ones), and that polls work fine. 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 four sentences long, each serving a purpose: purpose, return format, parameter usage, and additional context (polling/alternative API). No unnecessary words, front-loads the key action.

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 explains the return format (source, citation_uri, payload). It covers filtering, mark_read behavior, polling suitability, and alternative access. All 5 parameters are addressed. The tool's usage pattern is 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?

Schema coverage is 100%, so baseline is 3. The description goes beyond by giving an example filter value ('sec_8k') and explaining the behavioral impact of mark_read ('so the next call only shows newer ones'), adding practical meaning.

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

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

The description specifies exactly what the tool does: 'Pull fired events from your subscription feed.' It clearly identifies the resource (alerts) and action (pull), and distinguishes from sibling tools like list_subscriptions or subscribe by focusing on alert retrieval.

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

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

The description provides context for usage: it mentions polling is fine and notes an alternative API endpoint at GET registry.pipeworx.io/alerts.json for scripts and dashboards. However, it does not explicitly state when to use this tool versus sibling tools like list_subscriptions or recall, leaving that inference to the 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 indicate read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: parallel fan-out to multiple APIs, fallback logic, soft-fail for patents, return structure with changes grouped by source, total count, and citation URIs. 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 a single paragraph but well-organized with examples, followed by functionality, then sibling reference. No redundant sentences, though could benefit from more structured formatting (e.g., bullet points).

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

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

Given complexity (multiple sources, fallbacks) and no output schema, description covers overall behavior and output composition. Mentions return fields but not pagination or limits. Mostly complete for a 3-param tool with strong annotations.

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 three parameters with descriptions. Description adds further meaning: explains `since` format (ISO vs relative) with examples and typical recommendation, clarifies `value` accepts ticker or CIK. Adds marginal value 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?

Description clearly states it provides a change feed for a company using parallel calls to SEC, GDELT/GNews, USPTO. It distinguishes from sibling entity_profile by specifying static profile usage. Examples of user queries clarify the tool's purpose.

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

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

Explicitly gives query examples and when to use, plus an alternative (entity_profile for static data). Includes fallback logic (GDELT preferred, GNews on rate-limit) and soft-fail for USPTO. Provides guidance on `since` parameter format and typical usage.

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

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

Discloses memory scoping by identifier, persistence differences for authenticated vs anonymous users, and mentions 24-hour retention. No contradictions with annotations (idempotentHint=true aligns with storing data).

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

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

Highly concise with three front-loaded sentences covering purpose, usage, and details. Every sentence adds value, no wasted words.

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

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

For a simple 2-parameter tool with no output schema and clear annotations, the description covers all necessary context: purpose, storage semantics, scoping, and persistence behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description adds naming conventions (e.g., 'subject_property') and value content examples, providing extra meaning beyond the schema.

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

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

The description clearly states the tool saves data for reuse, specifies key-value storage, and distinguishes from siblings by mentioning 'scoped by your identifier' and pairing with recall/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 'use when you discover something worth carrying forward' and guides to pair with recall/forget, providing clear context for when to use this tool versus alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds that calls cascade through multiple endpoints, auto-disambiguates inputs, and details return values for each type, providing useful behavioral context.

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

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

Description is well-structured with example queries, purpose statement, and then detailed type sections. It is front-loaded and contains no filler, though slightly longer than minimal.

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 (entity resolution) and no output schema, the description adequately explains input types, return values for both entity types, and internal cascading behavior. Missing details like error handling or rate limits, but 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?

Schema description coverage is 100%, so parameters are already documented. The description adds concrete examples of valid inputs (e.g., ticker, CIK for company; brand/generic name for drug) and explains auto-disambiguation, going beyond schema basics.

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

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

Description starts with example queries and clearly states it resolves names to canonical IDs. It distinguishes from siblings by positioning itself as a preliminary step for other tools, and details two supported entity types with their return structures.

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

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

Explicitly advises 'Use FIRST whenever you have a name but need an ID.' It implies usage context and mentions it replaces multiple lookups, but does not explicitly state when not to use it or provide direct alternatives among 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, openWorldHint, idempotentHint, destructiveHint false, so safety is clear. The description adds behavioral details: it probes each entity with ai_visibility_check, performs ranking, and returns a ranked list with score/confidence/signal density. 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 four sentences, front-loading the core purpose, then method, use case, and output. Every sentence adds value without redundancy.

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

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

With 4 parameters (all documented) and no output schema, the description covers the tool's behavior, input, and output structure (ranked list with score, confidence, signal density). Could specify exact output fields but sufficient for agent use.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning (e.g., '_apiKey passed to api.anthropic.com per probe', 'first entity treated as subject'), but mostly reiterates schema content.

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

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

The description specifies a clear verb ('Compare AI visibility') and resource ('multiple entities side-by-side'). It explicitly states the method (probes each entity with ai_visibility_check, ranks by score) and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description provides concrete use cases ('competitive AI-marketing audits') and an example question. It implies when to use (comparing multiple entities) but does not explicitly state when not to use or name alternatives, though sibling tools offer context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns.' This warns about potential delays and failure modes without contradicting annotations.

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

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

The description is a single paragraph but front-loads the core purpose and fans-out services. Every sentence adds value: use cases, return structure, ecosystem scope, and failure behavior. No fluff or redundancy. Appropriate length for a composite tool.

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

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

Despite lacking an output schema, the description thoroughly explains the return format: 'summary block (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and a list of recent alternative versions.' Combined with input schema and annotations, 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?

Input schema has 100% coverage with clear descriptions for both parameters (package and version). The description does not add meaning beyond the schema, as it only repeats the default version behavior and mentions scoped packages, which are already in the schema. With full schema coverage, 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's purpose: a composite check for npm package quality using deps.dev and bundlephobia. It specifies the verb (scan_dependency), resource (npm packages), and scope (NPM only), distinguishing it from sibling tools that handle other ecosystems or 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?

Explicitly states when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear guidance on 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, idempotent, non-destructive behavior. The description adds important constraints: indexes only default branch, ignores common terms, rate-limited to ~10 searches/min, providing transparency beyond structured fields.

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 with about 5 sentences, front-loaded with purpose and usage. Some repetition of qualifiers could be streamlined, but overall efficient and well-structured.

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

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

Given no output schema, the description explains return type (files with repo, path, URL). It covers purpose, usage, limitations, and return format, making it fairly complete for a read-only 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 coverage is 100% with parameter descriptions. The description adds value by detailing supported qualifiers (repo:, org:, language:, etc.) and providing query examples, enhancing understanding 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 clearly states the tool's purpose: 'Search CODE across public GitHub repositories' to find definitions or usages of functions/symbols/strings. It distinguishes from siblings by specifying preference over web search and listing typical 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 gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for "find code that does X"...' and provides examples. It does not directly contrast with sibling tools like search_repos or search_within, but the 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's safety information is redundant. Description adds that results include specific fields but no additional behavioral traits like pagination or rate limits.

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

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

Two sentences, front-loaded with action and resource, no redundant words. 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 output schema exists, the description adequately lists return fields and usage context. No significant gaps for this simple, well-annotated 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 the description adds no new meaning beyond what the schema provides. It mentions 'keyword' which parallels the query parameter, but provides no extra detail.

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 'Search GitHub repositories by keyword' with specific verb and resource. Lists return fields, distinguishing it from sibling tools like 'get_repo' and 'search_within'.

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 context: 'Use when exploring projects or finding code implementations.' While it doesn't explicitly exclude other uses or name alternatives, the guidance is clear and actionable.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flag, and returns offsets for verification. This goes well beyond annotations.

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

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

The description is a single paragraph but packs all needed information without verbosity. It front-loads purpose and usage, then adds details. Slightly more structure (e.g., bullet points) could improve scannability, but it remains concise and effective.

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

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

Given no output schema, the description compensates fully by explaining return format (passages with offsets and scores), embedding model, windowing, and truncation. For a search tool with excellent annotations and full parameter coverage, this is complete enough for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for parameters; it repeats limit info and gives query examples but no new constraints or syntax. Schema already provides adequate parameter descriptions.

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

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

The description clearly states the tool's action: semantic search inside a fetched record. It specifies the verb 'search', the resource 'inside a record', and differentiates from siblings by mentioning the companion tool ask_pipeworx_grounded. The purpose is 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 to use when the record is too large for the prompt and pairs with ask_pipeworx_grounded. However, it does not explicitly exclude alternative tools like ask_pipeworx from the sibling list, leaving room for slight ambiguity about when not to use this tool.

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

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

Description provides details on delivery channels, verification, and limits. However, annotations say idempotentHint=true, but subscription creation is not idempotent (each call creates a new subscription). This contradiction lowers the score.

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 fairly long but structured logically: purpose, return, prerequisite, types, delivery channels. Every sentence adds value; could be slightly trimmed but not wasteful.

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

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

Covers prerequisites, types, parameters, delivery, and return value (id). No output schema, so return is briefly stated. Sufficient for the tool's complexity, though more detail on error cases could help.

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

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

Schema coverage is 100% and description adds significant value by explaining each subscription type's parameters with examples (e.g., items codes, delivery options, webhook signing). Goes beyond schema syntax.

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 creates a proactive monitoring subscription and returns an id. Distinguishes from siblings like unsubscribe and list_subscriptions by focusing on creation.

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

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

Explicitly states when to use (subscribe to alert stream) and prerequisite (Pipeworx OAuth account). Does not explicitly list when not to use, but context with sibling tools implies creation vs. listing/unsubscribing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these by detailing that the tool returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. 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 relatively long but well-structured with trigger phrases upfront, followed by explanation of return content and parameter behavior. It is informative without unnecessary repetition, though it could be slightly more concise.

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

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

The description explains the return structure (category-bucketed example questions with tool+argument shapes) and mentions the live catalog. Given no output schema, this is sufficient context for the agent to understand the tool's output. The tool is simple with one optional parameter, so completeness is adequate.

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

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

Schema coverage is 100% with the topic parameter described. The description adds value by providing example topic values (finance, pharma, etc.) and explaining the behavior when omitted (cross-category spread), which aids the agent in parameter selection.

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

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

The description clearly states the tool is an onboarding entry point for an agent to discover what can be asked. It lists specific verb-resource pairs (return category-bucketed example questions) and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by mentioning meta-tools and 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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains the optional topic parameter to focus the results. While it doesn't explicitly state when not to use, the guidance is clear and helpful for onboarding.

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 not read-only, not destructive, and idempotent. The description adds valuable context: the row is deactivated (not deleted), and historical events remain available via 'recent_alerts'. This goes beyond the annotations with no contradictions.

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

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

Two concise sentences. The first sentence delivers the core purpose, and the second adds behavioral context. No unnecessary words.

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

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

For a simple, single-parameter tool with no output schema, the description covers essential context: what happens to the data (deactivated, not deleted) and side effects (history stays). Could hint at success/failure indicators but suffices.

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

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

Schema coverage is 100% for the single parameter 'id', which is described as 'Subscription id (uuid) returned by subscribe.' The description adds context by mentioning 'by id' and connecting it to 'subscribe', reinforcing the parameter's 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 the action ('Cancel a subscription by id'), specifies the resource ('subscription'), and the identifier ('id'). It distinguishes from sibling tools 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?

The description includes an explicit condition: 'Ownership is enforced — you can only cancel your own subscriptions.' This guides when to use the tool, though it doesn't explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description supplements these by detailing the return format (verdicts, structured form, actual value with citation, percent delta) and the data source (SEC EDGAR + XBRL). It does not cover failure modes or limitations, but adds meaningful behavioral context beyond annotations.

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

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

The description is appropriately sized given the tool's complexity. It front-loads example triggers, then explains usage, supported domain, and return structure. Every sentence adds value, though it could be slightly trimmed.

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

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

Despite lacking an output schema, the description covers the return types (verdicts, structured form, value, citation, delta). It specifies the supported domain (company-financial for public US companies). It is nearly complete, but could mention handling of non-supported claims (e.g., returning 'unsupported' or 'inconclusive').

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% (one parameter 'claim' described). The description adds context: the claim should be natural language, gives examples, and specifies the domain (company-financial). This adds meaning beyond the schema's basic description.

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

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

The description clearly identifies the tool's purpose: to validate natural-language claims (specifically company-financial claims) against authoritative sources (SEC EDGAR + XBRL). It provides example phrasings and distinguishes itself from siblings by being a specialized claim verification tool, not a general research 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 states when to use: 'whenever the agent needs to check whether something a user said is factually correct' and specifies the supported claim type (company-financial for public US companies). It does not explicitly exclude other claim types, but the domain limitation is clear. It also notes efficiency gains over alternative approaches.

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