Wakatime

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

Annotations already declare readOnly, idempotent, non-destructive, open-world. Description adds critical context: per-model response structure (score, confidence, signals, raw_response) and that Anthropic calls incur direct costs for the user, which annotations don't cover.

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, no filler. Front-loaded with core action and outcome, then model details and use cases. Every sentence serves a purpose—no tautology or redundancy.

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

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

Given no output schema, the description partially specifies return structure (per-model score, confidence, signals, raw_response, combined view). Also addresses cost implications for Anthropic. Slightly missing details on error handling or rate limits, but adequate for an AI agent to infer usage.

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

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

All 4 parameters are documented in the schema (100% coverage). Description adds examples for 'entity' (e.g., 'Pipeworx'), clarifies model list semantics, explains _apiKey's purpose and cost implication, and provides disambiguation context for the 'context' parameter.

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

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

The description uses specific verbs ('probe', 'score') and identifies the resource (LLMs, entity visibility). It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on brand/business/product awareness scoring across models.

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

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

Provides explicit use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains model selection (default Workers AI, optional Anthropic with API key). Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations already indicate read-only, open-world, idempotent. The description adds that it routes questions to 3,775 tools and returns structured answers with citation URIs, providing useful behavioral context beyond annotations.

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

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

The description is front-loaded with the key instruction and uses bullet-like examples. It is slightly verbose but every sentence adds value. Could be trimmed without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description provides sufficient context: when to use, how it works, and examples. It covers the necessary aspects for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description does not add new meaning beyond the schema, which already explains the 'question' parameter accepts natural language. This meets the baseline expectation.

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 answers factual questions using structured data from many sources, with specific examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It explicitly distinguishes from web search, making the purpose unmistakable.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and lists numerous query types and example phrases. However, it does not differentiate from sibling tools like 'ask_pipeworx_grounded', which could cause confusion.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description details that it costs an extra LLM call, returns explicit refusal reasons, and confines answers to tool result. 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?

Well-structured and front-loaded with key info, but somewhat lengthy with some redundancy (e.g., 'Same routing as ask_pipeworx'). Still efficient for the detail provided.

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 fully explains return format, failure modes, and usage context. Covers all necessary aspects for an agent to use the tool safely and effectively.

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

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

Schema coverage is 100% with aliases well-documented. Description adds no additional parameter semantics beyond indicating natural language input, which is already clear from schema. Baseline 3 is appropriate.

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

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

Clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from sibling ask_pipeworx by specifying that it extracts answers only from tool results. Provides specific use cases (financial verdicts, legal claims, medical lookups).

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also advises to 'prefer ask_pipeworx for casual lookups,' providing clear alternative guidance.

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

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

The description extensively discloses behavioral details far beyond annotations (readOnlyHint, idempotentHint, etc.). It explains the fan-out process, response shapes, resolver contract, safety mechanisms (low-confidence short-circuits, closed/dead markets), wide-spread market handling, and resolution-rule risk. No contradictions to annotations.

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

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

The description is lengthy but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the main purpose. While dense, every sentence adds value for a complex tool; minor reduction could be possible.

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 (3 params, no output schema, rich annotations), the description is extremely complete. It covers edge cases (e.g., low-confidence matches, closed markets, wide spreads), resolution rules, and error states. An agent can confidently use the tool based on this description.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning by explaining the market input format in more detail, depth enum values, and the behavior of include_raw (summary vs full payloads). Examples in the schema further enhance 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?

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't explicitly mention when not to use or point to alternatives, the context is clear and the examples cover the main 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, so the agent knows it's safe. However, the description adds no behavioral details like what 'recent' means, default ordering, or pagination behavior.

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

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

Extremely terse (2 words). While concise, it sacrifices informative content, making it underspecified for the agent.

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

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

With 5 parameters, 0% schema coverage, and an output schema not detailed, the description is insufficient. It fails to cover necessary 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 description coverage is 0%. The description only indirectly mentions 'project', but does not explain 'user_id', 'page', 'author', or 'branch'. Most parameters remain undocumented.

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 'Recent commits for a project' indicates the tool returns commits, but lacks a verb and specific resource scope. It is clear but not precise, and does not distinguish from sibling tools like 'durations' or 'heartbeats'.

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

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

No guidance on when to use or not use this tool. Siblings include many tools, but no alternatives or context are provided.

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, and non-destructive behavior. The description adds important context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is well-structured with front-loaded examples and purpose. Each sentence adds value, explaining why to use, what data is pulled, and output format. Slightly long but efficient for the information density.

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 return format (paired data, citation URIs), data fields (revenue, net income, etc.), and sorting. Adequate for a comparison tool with two 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 clear enum and array descriptions. The description adds significant meaning: explains data sources per type, naming conventions (tickers/CIKs for company, drug names), and sorting behavior, going 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 performs side-by-side comparisons of 2-5 entities (companies or drugs), with example queries and explicit preference over sequential lookups. It distinguishes itself 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?

The description provides clear when-to-use guidance (comparing entities, ranking) and explicitly states to prefer this over sequential lookups. It does not explicitly mention when not to use, but context implies single-entity lookups are better served by siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds no further behavioral context. With rich annotations, the bar is lower, but the description doesn't provide additional value beyond what's in the 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?

Two words, front-loaded, no waste. Could be slightly more descriptive ('Returns the profile of the currently authenticated user'), but adequate for a simple tool.

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

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

Given zero parameters, an existing output schema, and comprehensive annotations, the description is complete. It provides the essential purpose without missing information.

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?

No parameters exist. Schema coverage is 100% (no params to document). Baseline for 0 params is 4. Description adds no param info, but none is needed.

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

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

The description 'Authenticated user profile.' clearly states the tool returns the profile of the currently authenticated user. It distinguishes itself from sibling 'user' by specifying 'current', making the purpose specific and unambiguous.

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

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

No explicit guidance on when to use vs alternatives. While it's clear it's for the current user, there is no mention of when not to use it (e.g., for other users) or comparison with siblings like 'user'.

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 behavior beyond annotations: fact-checked citations, gaps array, never invents facts, parallel execution, and account/plan requirements. Annotations already mark readOnly, openWorld, idempotent, non-destructive, so 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 information-dense yet well-structured, with each sentence adding critical context. No fluff or redundancy; front-loaded with the core value proposition.

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

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

Given no output schema, the description adequately explains the return format (structured findings packet with citations, confidence, gaps). Covers purpose, process, prerequisites, latency, and alternatives.

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 description adds value by explaining depth enum meanings (quick=3, standard=5, thorough=8 paid plans) and clarifying that question can be broad/multi-part.

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

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

The description explicitly states it performs 'Grounded multi-source research in ONE call' by decomposing questions, routing to 3,775 tools in parallel, and extracting grounded answers. It distinguishes from sibling tool ask_pipeworx for single lookups.

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

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

Clearly advises when to use (broad/multi-part questions) and when not (use ask_pipeworx for single lookups). Also specifies prerequisites (Pipeworx account, paid plan for 'thorough' depth) and expected latency 15-60s.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral details about the output: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations to explain what the user gets.

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

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

The description is informative and each sentence adds value: purpose, domain examples, return details, usage guidance. It is front-loaded with the core action. Slightly longer than necessary but no wasted words.

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

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

Given the complexity (6 params, many aliases) and missing output schema, the description compensates by detailing what is returned. It covers the key aspects for a discovery tool. However, it does not mention error handling or empty results.

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

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

Schema coverage is 100% with descriptions for all parameters, including aliases. The description does not add significant new information about parameters beyond the schema; it only provides example queries. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It includes a broad list of example domains and explains that it returns ready-to-call schemas. This is specific and distinguishes it from siblings, which are other tools in the system.

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 tells when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for usage and excludes single-answer scenarios.

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

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

Annotations already declare safe read-only behavior. The description adds no behavioral context beyond the minimal phrase, such as what data is returned, pagination, or rate limits. It provides no additional 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?

While short, the description is under-specified rather than concise. Every word should add value; here, five words provide almost no useful information. A longer, clearer description would better serve the agent.

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

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

Given 8 parameters, extensive siblings, and the need for disambiguation, the description is grossly incomplete. Even with an output schema, the agent cannot determine what 'durations' this tool retrieves or how to use it effectively.

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

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

With 0% schema description coverage and 8 parameters, the description should explain key parameters. It mentions none, leaving the agent to guess what 'duration' parameters mean (e.g., date format, required fields like user_id).

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

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

The description 'Durations for a date' is vague and fails to specify what kind of durations (e.g., coding time, project durations). It does not distinguish the tool from siblings like 'heartbeats' or 'stats', which may also return time-based 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?

No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives (e.g., for retrieving specific duration metrics versus aggregated summaries), nor does it mention prerequisites or exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no behavioral context beyond the name, such as data freshness, pagination, or access constraints. With rich annotations, the bar is lower, but the description still adds no value.

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

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

The description is extremely concise at four words. It clearly states the resource ('editors') and nature ('public stats'). While minimal, it earns its place by providing a basic purpose without unnecessary fluff.

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

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

Given the tool's simplicity (no parameters, output schema exists, rich annotations), the description is minimally adequate. However, it lacks context about what the stats represent and how to interpret the output, which could be further clarified without repeating schema information.

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?

There are no parameters, and schema description coverage is 100%. According to guidelines, baseline is 3 since no parameter information is needed. The description does not add semantics for parameters, which is acceptable here.

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 'Public editor stats.' indicates the tool provides statistics about editors and that the data is public. However, it is vague about what specific stats are included, and does not distinguish it from sibling tools like 'stats' or 'commits' which might also provide editor-related 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?

The description offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context for appropriate use, forcing the agent to infer from the name and schema alone.

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 details that it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and lists exactly what is returned. It also notes a soft-failure for patents (USPTO API sunset) and that it's a parallel call. Annotations indicate read-only, non-destructive, idempotent; description adds significant 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 dense and front-loaded with examples and key instructions. It contains valuable details about return fields and caveats. While long, every sentence earns its place. Minor reduction possible but still 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?

Without an output schema, the description fully explains what is returned (CIK, filings, fundamentals, patents, news, LEI) and provides context on the patents soft-failure. The input parameters are thoroughly described. No gaps remain for the tool's intended use.

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

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

Schema coverage is 100%, and description largely repeats the schema's parameter descriptions (type enum with 'company', value as ticker or CIK). It adds a note about name not supported and to use resolve_entity, which is helpful but not a major extension. Baseline 3 applies.

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

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

The description starts with concrete user queries and clearly states it returns a full cross-source profile of a US public company. It distinguishes itself from sibling tools by stating it should be preferred over chaining single-pack lookups, and mentions resolve_entity for name resolution.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states when not to use: names not supported, and directs to resolve_entity first. Provides clear alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds use-case context but does not disclose details like irreversibility or success/error responses. 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?

Three sentences, front-loaded with the main action, no wasted words. Efficient and to the point.

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?

Provides adequate context for a simple tool with one parameter and no output schema. Could mention return behavior but not critical. Relates well to sibling tools.

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 already describes 'key' as 'Memory key to delete'. Description does not add additional meaning beyond 'by key', so baseline 3 applies.

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

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

Clearly states the action ('Delete a previously stored memory by key') and identifies the resource (memory). Differentiates from siblings by mentioning pairing with 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?

Provides explicit when-to-use guidance: stale context, task done, clear sensitive data. Implicitly contrasts with remember and recall, but no explicit when-not-to-use.

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

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

Annotations indicate read-only and idempotent behavior. The description adds context by explaining the external page fetch, extraction of title/description/links, and standard markdown output. It openly discloses the process beyond annotations.

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

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

The description is three sentences plus a bulleted usage list, front-loading the core action and output format. Every sentence adds value, making it highly efficient and well-organized.

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

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

Given the simple parameters and no output schema, the description covers purpose, usage, and output format ('single text blob', 'standard llms.txt markdown format'). It omits error scenarios or prerequisites but is sufficiently complete for a read-only tool.

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

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

With 100% schema coverage, both parameters are well-documented in the schema. The description does not add new meaning beyond restating the schema's explanation of max_links default and max. Baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file', stating exactly what the tool produces. It distinguishes itself from siblings by naming the standard output format and use cases for AI crawlers, which no other sibling does.

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

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

The description provides explicit use cases (client site, own project, competitor audit) but does not include when not to use it or mention alternatives among siblings. It offers clear context for correct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which describe safety and behavior. The description adds no behavioral context beyond the fact that it returns goals, so it adds minimal value.

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

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

The description is extremely concise at two words, but this brevity comes at the cost of essential information. While it is front-loaded, it fails to provide needed context.

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

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

Given the existence of an output schema and annotations, the description is still incomplete. It does not explain what the output contains, how pagination works, or any additional context needed for a tool that returns goals.

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 0%, meaning no parameter descriptions exist. The description 'User's goals' does not explain the meaning or usage of the 'page' or 'user_id' parameters, leaving the agent without guidance.

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 'User's goals' clearly indicates the tool returns goals for a user, but it lacks specificity about what kind of goals or how they are structured. It is not a tautology and distinguishes from siblings by topic.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It relies entirely on the tool name and user inference.

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, and destructiveHint=false, so the description adds no behavioral context beyond confirming it returns raw data. The description does not contradict annotations.

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

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

The description is extremely brief (7 words) but too short to convey sufficient information. It sacrifices clarity for brevity, making it under-specified rather than efficiently concise.

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

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

Given the low complexity (2 parameters, annotations present, output schema exists), the description minimally identifies the tool's purpose. However, it fails to explain what a heartbeat is or the format of the data, leaving gaps for an AI agent.

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

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

Schema description coverage is 0% and the description adds no meaning to the two parameters ('date', 'user_id'). The examples in the schema provide some context, but the tool description itself is silent on 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 'Raw heartbeats for a date' implies retrieval of heartbeat data for a specific date, but does not explicitly state the action (e.g., list, get) or define what 'heartbeats' means. It is somewhat vague but not a tautology; it distinguishes from siblings like 'stats' or 'commits' by mentioning 'raw heartbeats'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'stats' or 'durations'. There is no mention of when not to use it or any prerequisites.

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 (readOnlyHint, idempotentHint) already indicate safe, idempotent behavior. The description adds no further behavioral context (e.g., pagination, filtering, or data freshness) 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?

While extremely concise, the single sentence is under-specified and not informative. Conciseness should not come at the cost of missing 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?

Given 3 optional parameters and an output schema, the description lacks completeness. It does not explain what the leaderboard displays, how parameters affect results, or how to interpret the output.

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

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

Schema description coverage is 0%, but the description provides zero information about parameters (page, language, country_code). It fails to explain their purpose or allowed values.

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

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

The description 'Public leaderboard.' is vague; it identifies the resource but lacks a specific verb or context (e.g., 'List top users by points'). It barely distinguishes from sibling tools like 'stats' or 'current_user'.

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

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

No guidance on when to use this tool over siblings like 'stats' or 'entity_profile'. No context on prerequisites or appropriate scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds the return field list but doesn't elaborate on behavior like default pagination or what 'active' means. Moderate added value 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 the core purpose, no wasted words. Efficient and clear.

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

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

The tool is simple with one optional parameter, no output schema, and rich annotations. The description covers purpose, usage, and return fields completely. 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 clear description of the only parameter (include_inactive). The tool description does not add extra meaning to the parameter, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and it lists the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use it and why, and implicitly suggests alternatives (subscribe, unsubscribe).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no additional behavioral context beyond confirming it returns 'current' meta. No contradiction; but for a tool with full annotations, the description could still detail output characteristics.

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?

Extremely concise (4 words) but lacks substance. Front-loaded but insufficient for understanding. Simple structure is appropriate, but the content is too minimal to be helpful.

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?

Output schema exists, so return values need not be described. However, the description fails to clarify the nature of 'meta', leaving ambiguity about the tool's utility. Given low complexity, a more informative description is expected.

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?

No parameters exist (0 params, 100% schema coverage). Baseline is 4; description need not add parameter info. The tool is trivially parameterized.

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 'Current API meta.' is vague; it states it returns API metadata but does not specify what kind (e.g., version, capabilities). The tool name 'meta' alone is ambiguous. It does not clearly differentiate from sibling tools like 'discover_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?

No guidance on when to use this tool vs alternatives. The description does not mention prerequisites, context, or exclusions. With many sibling tools, the agent lacks direction for selection.

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

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

The description discloses rate limits (5 per identifier per day), that it's free and doesn't count against quota, and how feedback is processed (digests read daily, affects roadmap). This adds significant context beyond annotations, which are mostly false for readOnlyHint, idempotentHint, destructiveHint.

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 well-structured: starts with purpose, then usage conditions, then format instructions, then behavioral details. 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?

Given the tool's simplicity (no output schema), the description covers all necessary aspects: what it does, when to use, how to format input, constraints (rate limits, quota), and impact. 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 description coverage is 100%, but the description adds value by explaining enum choices in more detail for 'type', describing the optional 'context' object's intent, and giving guidelines for the 'message' parameter (specificity, length).

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 send feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It defines each feedback type and distinguishes the tool from its siblings, which are mostly data retrieval or analysis tools.

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

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

The description explicitly lists when to use the tool (bug, feature, data_gap, praise) and provides guidance on how to structure the message (describe in terms of Pipeworx tools/packs, don't paste end-user prompt). It also mentions rate limits and free 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the agent knows it's safe. Description adds valuable context: self-aggregating from CF analytics-engine, no PII, caching behavior (5min-1h). This goes 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?

Four sentences with clear structure: main function, use cases, additional notes. No filler. Every sentence adds value.

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

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

Given one optional parameter, no output schema, and comprehensive annotations, the description fully covers what the tool does, its inputs, caching, and purpose. 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 provides enum and description for window parameter. Description reinforces the meaning of each window and adds practical guidance on when to use short vs long windows. Schema coverage is 100%, so baseline is 3; description adds value above baseline.

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

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

Description uses specific verb 'returns' and explicitly states the resource: top tools, top packs, and total call volume over a recent window. It clearly distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending analytics.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and contrasts window sizes. However, it does not explicitly state when not to use the tool or provide alternative tools for different 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 indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral details: fill checks, similarity filters, partition placeholder handling, and warning when realizable edge is ≤0. No contradiction; description enhances transparency 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 long but well-structured with paragraphs and bold keywords. It front-loads the requirement and then explains systematically. While every sentence adds value, some redundancy exists (e.g., partition filter explanation could be tighter). Still very efficient for the complexity.

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

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

Despite no output schema, the description thoroughly explains the response structure: opportunities array with fields, partition_check object, fill check results. It also references sibling tool polymarket_fill_risk for custom sizing, making it fully actionable and 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%, but the description adds substantial value: explains both modes with examples, formats (slug/URL for event, seed question for topic), and behavioral context like the semantic anchor and partition filter. This greatly aids parameter understanding.

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

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

The description explicitly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) with clear explanations, making it highly specific and distinct from sibling tools.

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

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

The description provides explicit requirements: 'REQUIRES one of event OR topic — call with no args fails.' It recommends event mode for specific markets and topic mode for cross-event scanning, and includes conditions like Jaccard similarity and partition filter thresholds, guiding proper use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds valuable behavioral context: caching at KV level (1h), diagnostics for empty segments, separate handling of Fed bets with reliability warning, and detailed model family descriptions. No contradictions with annotations.

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

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

Description is very long (multiple paragraphs) with dense technical detail. While each sentence adds value for the complex model explanations, it could be more streamlined for quicker comprehension. Front-loading is limited; the main verb appears in the first sentence, but detailed model breakdowns follow.

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 thoroughly explains response structure (by_segment, fed_candidates, _diagnostics) and key fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h-move warning). Covers all nine parameters with extra context. No gaps for the intended use case of scanning opportunities.

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 9 parameters with descriptions. Description adds extra meaning beyond schema: explains relationship between min_partition_leg_kelly and min_kelly, clarifies min_liquidity context ('walk the book'), and max_spread_pp's impact. While schema is sufficient, description enriches understanding.

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

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

Description explicitly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb (scan, return), resource (Polymarket markets), and unique differentiator (Pipeworx disagreement). This distinguishes it from sibling tools like polymarket_arbitrage and bet_research.

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

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

Clearly identifies use case as 'what should I bet on today' and explains tradeable-edge knobs (min_liquidity, max_spread_pp) to filter realizable opportunities. However, does not explicitly contrast with alternatives like polymarket_arbitrage or bet_research, leaving some ambiguity about when to prefer this tool over 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description goes beyond by detailing telemetry construction from daily snapshots, history bounded by 60-day TTL, decay computed from daily closes (not intraday), and response fields like trend and decay_pp_per_day. No contradictions with annotations.

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

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

The description is well-organized: purpose first, then a question, then arguments, then detailed response structure. It's informative but could be more concise (e.g., condensed expiration description). However, every sentence adds value, and structure is clear.

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

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

No output schema, so the description fully explains the response: tracked[] with time-series, trend, decay; expired[] with lifespan; snapshot_dates[]. Also covers limits (60-day TTL, snapshot enablement, daily closes). Complete and actionable.

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

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

Schema coverage is 100%, both parameters have descriptions. The description adds context: default values, maximum days, and explains that 'window' refers to snapshot family. It doesn't duplicate schema but adds meaning (e.g., 'snapshot family' interpretation). Minor discrepancy: description says 'max 30' while schema says 'clamp 2-30' (more precise).

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry. It asks a specific question ('how long has this edge existed and is it shrinking?') and explains the difference between a fresh wide edge and an old one. It distinguishes from siblings by focusing on historical persistence rather than current edges.

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

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

The description implies usage context by answering the persistence question, but it does not explicitly state when to use this tool versus siblings like 'polymarket_edges.' It could benefit from a 'use this for historical analysis, for current edges see polymarket_edges' note. However, the response structure and limits provide good contextual guidance.

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

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

Goes far beyond annotations by detailing return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.), explaining both modes, and warning about partial fills converting arb to directional position. Annotations already signal read-only and idempotent, but description adds crucial 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?

Well-structured with a one-sentence summary, uppercase flags for requirements, and clear separation of modes. Slightly verbose but every sentence adds value; could be tightened without loss of information.

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

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

Comprehensive for a complex two-mode tool with no output schema. Covers all return fields for both modes, explains edge cases (thin_legs, forced_directional_risk), and integrates with sibling tools. No gaps identified.

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, but description adds valuable context: 'size_usd interpreted as settlement notional S (shares per leg)' for basket, side defaults and auto-detection, and required one-of market/event. This adds meaning beyond the schema.

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

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

The description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishing it from siblings like polymarket_arbitrage and polymarket_edges. It explicitly separates single-market and basket modes with specific inputs and outputs.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing clear when-to-use and why (thin books, unhedged positional risk).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: it alerts about compatibility issues (non-equivalent bet shapes, semantic mismatch), temporal alignment, and skipped comparisons. This goes well beyond annotations without contradicting them.

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

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

The description is comprehensive but slightly verbose, with multiple paragraphs. However, it uses structured formatting (bold headers, bullet points) and groups related information, making it scannable. Could be tighter but effectively communicates complex concepts.

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 response fields: leg-by-leg prices, matched spreads, safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers edge cases where spreads are meaningless, making the tool safe to invoke without guesswork.

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 each parameter is described with examples and constraints. The description explains the topic shortcuts in detail, how explicit tickers override mapped values, and provides example values. This adds significant meaning beyond the schema itself.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It explains the two modes (topic shortcuts vs explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on the same resolving question across venues.

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 tells when to use each mode: topic for pre-mapped macros, explicit tickers for custom pairings. It also warns that pre-mapped topics often return compatibility_warning and are not automatically tradeable, guiding agents on when to avoid relying on the spread.

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, but the description adds no behavioral context beyond what's inferred from the name.

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?

Extremely short at two words, but this is under-specification rather than conciseness. No structure or front-loading of key information.

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

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

Despite having an output schema, the description fails to specify the tool's operation (e.g., listing projects for a user). It is incomplete for effective tool selection.

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 0%, so the description must explain parameters. It does not mention 'q' or 'user_id', leaving their meaning and usage completely undocumented.

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 is a noun phrase ('User's projects') that doesn't specify the action (e.g., list, retrieve). While annotations indicate read-only, the purpose is unclear without knowing whether it returns a list or a single 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?

No guidance on when to use this tool versus siblings like 'commits' or 'durations'. The description provides no context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is clearly safe. The description adds useful behavioral context: scoped to identifier, listing behavior when key omitted, and relationship to remember/forget.

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, no redundant information. The main action is front-loaded, and every sentence adds meaningful context about the tool's behavior and relationships.

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

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

For a simple tool with 1 optional parameter and no output schema, the description provides complete guidance: what it does, when to use, how it's scoped, and how it relates to siblings. Nothing missing given the 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 the schema defines the key parameter. The description adds value by explaining that omitting the key lists all saved keys, which is behavior not evident from the schema alone.

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

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

The description starts with a specific verb-retrieve' and resource (value saved via remember) and clearly explains how to list all keys. It also explicitly 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?

The description provides clear when-to-use guidance ('look up context the agent stored earlier') and gives practical examples. It does not explicitly state when not to use, but the context and pairing with remember/forget effectively imply alternatives.

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

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

The description adds behavioral context beyond annotations, such as the effect of setting mark_read:true to flag events as read, and explains the data shape (source, citation_uri, raw event payload). It does not contradict the annotations, which already indicate read-only and idempotent behavior.

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

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

The description is efficiently structured: starts with the high-level purpose, then details returned data, filtering options, a key parameter effect, and an alternative access method. It is informative without unnecessary words, earning its place in a few sentences.

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

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

Given there is no output schema, the description comprehensively covers the return shape (source, citation_uri, raw event), all parameters, a key behavioral effect (mark_read), and even mentions polling suitability and an HTTP alternative. It leaves no significant gaps for a read-only tool.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the purpose of each parameter in context (e.g., 'Filter by type', 'Set mark_read:true to flag returned events read so the next call only shows newer ones'). It also mentions the default limit (50) which is already in the schema but reinforces the behavioral 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?

The description starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It distinguishes from siblings by specifying it returns alerts from a persisted feed, which no other sibling tool appears to do. The description is specific and unambiguous.

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

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

The description provides guidance on when to use the tool ('Polls work fine') and mentions an alternative HTTP endpoint for scripts and dashboards, helping the agent decide between this tool and other access methods. However, it does not explicitly state when not to use it or compare to sibling tools directly.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds significant behavioral context: fan-out to multiple sources, GDELT preferred with GNews fallback, USPTO soft-fails until reactivated, and return format with structured changes, total_changes, and citation URIs.

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

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

The description is somewhat verbose but well-structured with key info front-loaded. It provides examples, edge cases, and fallback behavior. Could be trimmed slightly, but overall 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?

Despite no output schema, the description fully explains the return format (structured changes grouped by source, total_changes count, pipeworx:// URIs) and failure modes (GDELT→GNews fallback, USPTO soft-fail). This is comprehensive for a multi-source 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 does not need to repeat parameter definitions. However, it adds value by explaining 'since' accepts ISO date or relative shorthand with examples and recommends typical values ('30d' or '1m'). This goes beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company, listing what's new, latest, updates, etc. It specifies the fan-out to SEC EDGAR, GDELT→GNews, USPTO, and explicitly distinguishes from sibling entity_profile for static profiles.

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

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

Explicit usage examples ('What's new with X', 'latest on Y') are given, along with a clear when-not-to-use: 'Use entity_profile instead when you want the static profile... regardless of window.' This effectively guides the agent to choose the correct tool.

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

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

Annotations indicate idempotent and non-destructive behavior. Description adds key behavioral details: scoped by identifier, persistence differences between authenticated and anonymous sessions, and 24-hour retention. 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?

Four sentences pack all essential info: purpose, usage scenario, behavioral traits, and pairing with siblings. No redundant or missing elements.

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?

High schema coverage, informative annotations, and description collectively provide full context. No output schema needed; description covers usage, retention, and pairing adequately.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing example key patterns (subject_property, target_ticker) and explaining the value field's flexibility, improving beyond baseline.

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

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

The description clearly states the tool saves data for later reuse across conversations/sessions, and provides specific examples (ticker, address, preference) that distinguish it from sibling tools like recall 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?

It explicitly says when to use (discover something worth carrying forward) and mentions alternative tools (recall, forget). No ambiguity about 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 cover read-only and idempotent behavior. Description adds that each call cascades through multiple endpoints, replacing 2-3 manual lookups, and details return values per type. Does not discuss rate limits or disambiguation details beyond stating 'auto-disambiguated.'

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: starts with query examples, then purpose, usage guideline, then detailed per-type breakdown. A bit lengthy but every sentence adds value. Could tighten the opening quotes 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?

With no output schema, the description fully explains what is returned for each entity type, including specific fields and citation URIs. It covers input flexibility and auto-disambiguation, making it 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 already covers both parameters with good descriptions (100% coverage). Description adds examples of accepted input formats (ticker, CIK, name for company; brand/generic for drug) and explains outputs per type, providing meaningful 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 clearly states the tool resolves names to canonical identifiers, with specific examples and explicit connection to other tools needing those IDs. It distinguishes itself as the go-to resolution tool among siblings.

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

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

Includes explicit instruction 'Use FIRST whenever you have a name but need an ID.' Provides context on replacing manual lookups. Could be improved by stating when not to use (e.g., if you already have an ID), but overall 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?

The description details the internal process (probes each entity with ai_visibility_check, ranks by score) and output format (score, confidence, signal density). Annotations already declare read-only, idempotent, and non-destructive nature; the description adds context about the probing mechanism without contradiction.

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

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

The description is two sentences: the first states the primary action, the second provides use case and output details. No extraneous information; 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 4 parameters and no output schema, the description sufficiently explains the output (ranked list with score, confidence, signal density) and the internal behavior (probing each entity). No additional context 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%, so baseline is 3. The description adds value by explaining that the first entity is treated as the subject, context disambiguates common names, and models have defaults with API key requirements. 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 explicitly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and returns a ranked list. This clearly distinguishes it from the single-entity ai_visibility_check sibling 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 provides a concrete use case ('competitive AI-marketing audits') with an example question. However, it does not explicitly state when not to use this tool or directly mention the sibling ai_visibility_check as an alternative for single-entity queries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: partial failures degrade gracefully (sources_failed listed), bundlephobia first measurement can take 5-30s, and the composite nature (fans out across multiple services). 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 relatively long but highly informative. It front-loads the main purpose and uses bullet-like structure for return values. Every sentence adds value; however, it could be slightly tightened without losing information.

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

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

Given the complexity of the tool (multiple data sources, partial failures, timing constraints), the description covers all essential aspects. It explains the return structure (summary block, per-advisory, links, alternatives). Without an output schema, this is sufficiently complete for an agent to understand behavior and results.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds minor value by mentioning that scoped packages are accepted and default version behavior ('Defaults to the latest published version when omitted'). This is adequate but not substantial 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 is a composite check for assessing npm packages, covering license, advisories, version history, and bundle size. It uses specific verbs ('scan', 'fans out') and resource ('npm package'), and distinguishes itself from sibling tools by its unique composite nature.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides context for when not to use: '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?

The description adds significant behavioral detail beyond the annotations: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and return of character offsets and similarity scores. 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?

Every sentence is purposeful, front-loaded with core functionality and usage. The description is compact yet comprehensive, with no redundant or vague phrasing.

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

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

Given no output schema, the description adequately explains return format (top-N passages with offsets and scores). All parameters are well-described, and annotations provide full safety profile. The tool is fully contextualized for an AI 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 adds extra value: clarifies max chars for 'text', default and range for 'limit', and provides illustrative examples for 'query'.

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 semantic search inside a fetched record, with concrete examples (SEC 10-K body, article). It distinguishes itself from siblings like ask_pipeworx_grounded by specifying it is for searching within a fetched record rather than over a whole document.

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 tells when to use: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also pairs with ask_pipeworx_grounded for grounded Q&A over relevant passages, providing clear guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no context beyond these, missing the opportunity to explain aggregation behavior, date ranges, or potential performance implications.

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?

Extremely brief (2 words), but this is underspecification rather than conciseness. The description does not earn its place as it fails to provide useful information.

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

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

Given 5 parameters, 2 required, and an output schema (not detailed), the description is completely inadequate. It does not clarify the purpose, parameters, or return value.

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 5 parameters (with 2 required) and 0% schema description coverage. The description does not mention any parameter names, types, or semantics, leaving the agent to infer from schema alone.

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

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

The description 'Aggregate stats' is a near-tautology of the tool name 'Stats', providing virtually no verb or resource specification. It fails to differentiate the tool from siblings like 'summaries' or 'durations'.

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

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

No guidance is given on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned.

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

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

Beyond annotations, the description discloses important behaviors: OAuth requirement, return value, delivery channel constraints (email/SMS verification, 10/day cap for SMS, auto-disable after 10 failures for webhook). No contradictions with annotations.

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

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

The description is well-structured and front-loaded, starting with purpose and prerequisites. It is somewhat lengthy due to comprehensive type examples, but every sentence adds value. Could be marginally tighter 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 complexity of 3 parameters including nested objects and an enum, the description covers purpose, all parameter behaviors, return value, prerequisites, and edge-case behaviors (e.g., webhook auto-disable). No output schema needed as return is clearly stated.

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 description adds significant value beyond the input schema by providing concrete examples for each type and detailed explanations of delivery parameters (e.g., webhook signing). This helps the agent correctly construct parameters.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb and resource, and distinguishes from sibling tools like list_subscriptions or unsubscribe.

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

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

The description provides clear context on when to use the tool, including prerequisites ('Requires a Pipeworx OAuth account') and limitations ('anonymous + BYO cannot persist subscriptions'). It does not explicitly mention alternatives but covers usage scenarios well.

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, idempotentHint, and destructiveHint. Description adds that it returns structured example questions and can be called with no arguments or a topic, which is consistent and adds value 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?

Well-structured with trigger phrases, output description, and usage advice. Slightly long but every sentence earns its place; could be marginally 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?

With no output schema, the description adequately explains the return format (category-bucketed examples with tool shapes). Complete for a simple one-parameter tool.

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

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

Schema coverage is 100% for the single parameter. Description enhances by listing example values (finance, pharma, etc.) and explaining omission behavior, adding significant meaning beyond the schema's description.

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

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

The description clearly states it returns category-bucketed example questions with tool and argument shapes, serving as an onboarding entry point. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_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 advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions optional topic filtering. Provides clear context for when to invoke.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read operations. However, the description adds no behavioral context, such as whether results are aggregated, the time range scope, or any specific constraints, missing the opportunity to add value 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 extremely brief (2 words) but this is under-specification, not conciseness. It lacks necessary detail to be useful, making it inefficient for agent decision-making.

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

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

Given the complexity (8 parameters, no schema descriptions) and the existence of an output schema, the description is completely inadequate. It does not explain what the tool returns, how parameters affect results, or any behavioral details, leaving critical 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?

With schema description coverage at 0%, none of the 8 parameters (e.g., start, end, project, timeout) are explained in the schema or the description. The description fails entirely to provide meaning for the parameters, leaving the agent with no guidance on how to use them.

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 'Daily summaries' is vague and almost tautological. It does not specify what kind of summaries (e.g., coding activity, time tracking) or the resource being summarized, making it difficult for an agent to understand 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?

No guidance is provided on when to use this tool versus alternatives like stats, durations, or leaders. There is no mention of prerequisites, exclusions, or context for 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?

The description explains beyond annotations: it clarifies that the row is deactivated (not deleted) and historical events remain via recent_alerts, adding valuable 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?

Three focused sentences with no wasted words, front-loading the main action and adding necessary constraints and side effects.

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 mutation with one parameter and no output schema, the description fully covers the effect (deactivation), constraints (ownership), and side effect (history retention).

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 parameter description is already provided. The description adds minimal extra meaning (linking id to subscribe), meeting baseline.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource, distinguishing it 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 specifies ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context, though it does not explicitly list 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context, but annotations cover the key traits. The description could mention that it is a read-only operation, but it's acceptable.

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

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

The description is extremely short ('Public profile.'), which is concise but overly minimal. It does not provide enough information to be useful, and while it is front-loaded, it fails to earn its place by adding value beyond the tool name.

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

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

Despite having an output schema, the description is too incomplete for a tool with one required parameter and no schema descriptions. The agent needs more context about what the public profile contains or what the user_id represents. The description fails to provide a complete picture.

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

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

The input schema has no description coverage (0%) and the parameter 'user_id' is just a string with no explanation. The description 'Public profile.' does not add any meaning to the parameter, leaving the agent to guess its format or semantics. This is a significant gap.

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 'Public profile.' clearly indicates the tool returns a user's public profile. The name and title are generic, but among siblings, this tool distinguishes by requiring a user_id, unlike 'current_user' which likely gets the current user. The purpose is clear and specific.

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

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

No guidance is provided on when to use this tool versus alternatives like 'current_user' or 'entity_profile'. The description lacks any usage context or prerequisites, leaving the agent to infer from the parameter.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, providing a strong baseline. Description adds details about the return structure (verdict with specific values, extracted form, actual value with pipeworx:// citation, percent delta), the underlying data sources (SEC EDGAR + XBRL), and that it replaces multiple sequential calls—all beyond the annotations.

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

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

Description is slightly long but efficiently packs multiple examples, usage context, and behavioral details. It is front-loaded with example patterns, making it easy to grasp. Every sentence contributes value, and no redundant information is present.

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

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

Despite lack of output schema, the description fully explains the return value (verdict, structured form, actual value, citation, delta). It covers the tool's domain limitations (company-financial claims), underlying data source, and how it replaces multiple calls—making it complete for an AI agent to understand and invoke correctly.

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

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

Schema description coverage is 100% (single parameter 'claim' with description). The description adds value by providing concrete examples ('Apple's FY2024 revenue was $400 billion') and clarifying that the parameter accepts natural-language claims, which exceeds the schema's brief description.

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

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

Description clearly states the verb (verify), resource (natural-language claims against authoritative sources), and scope (company-financial claims via SEC EDGAR + XBRL). Provides example queries and explicitly distinguishes from siblings by noting it replaces 4-6 sequential calls, making purpose unambiguous.

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

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

Description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain (company-financial claims). It does not explicitly mention when not to use or list alternative tools, but the context and examples provide sufficient guidance for appropriate usage.

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