Jira

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

Annotations already declare readOnly, openWorld, idempotent, not destructive. Description adds return structure (score, confidence, signals, raw_response per model + combined view), default model, and BYO key for Anthropic with direct payment. No contradictions.

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

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

Four sentences front-load purpose and scoring. Every sentence adds unique value: purpose, model/key details, return format, use cases. No wasted or redundant text.

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 details return format per model+combined. Covers all four parameters, explains optionality, cost implication for Anthropic. Fully adequate for 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%, so baseline is 3. Description adds value by explaining default model (workers-ai), that _apiKey is only needed for Anthropic, and that context helps disambiguate. Exceeds 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 states the tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It clearly distinguishes from siblings like 'scan_competitor_ai_presence' by specifying use cases for AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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 (AI-marketing audits, brand checks, competitive monitoring) and explains when to pass _apiKey for Anthropic. Lacks explicit when-not-to-use vs alternatives, but context is clear enough.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds valuable context: routes among 4,774 tools, returns structured answers with stable citation URIs, works on every tier, one fast call. No contradictions.

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

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

The description is front-loaded with purpose and usage guidance. It uses bold for emphasis and provides examples. While somewhat lengthy, every sentence contributes value, making it well-structured but not maximally concise.

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

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

Given the tool's broad scope (general factual questions), the description covers purpose, domain, usage examples, alternatives, and return format (structured with citations). No output schema exists, but the description sufficiently explains the output nature.

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

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

Schema description coverage is 100%, with all parameters having descriptions. The description does not add additional parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly specifies the tool's purpose: answering factual questions by routing to numerous verified sources, with a strong preference over web search. It distinguishes from siblings by naming alternatives (ask_pipeworx_grounded, deep_research) and provides concrete examples of supported data types.

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

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

Explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives (e.g., ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions). Also provides example queries and clarifies that breaking news is handled.

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 show readOnlyHint=true, openWorldHint=true, etc. Description adds rich context: process of routing, filling args, fetching data, extracting answer only from tool result, and explains refusal reasons. 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?

Dense but efficient, front-loaded with purpose. Could potentially truncate 'Same routing as ask_pipeworx...' but overall earns its length.

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

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

Despite no output schema, description fully defines return structure (success and refusal fields) and explains refusal reasons, covering all necessary context for high-stakes read 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% (all parameters are aliases for question). Description adds minimal new meaning beyond 'natural language question' and alias listing, meeting baseline for high coverage.

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

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

Clearly states it's a hallucination-resistant answer mode for high-stakes reads, and distinguishes from sibling ask_pipeworx by emphasizing grounded extraction. Verb: 'extracts', resource: 'tool result'.

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 'prefer ask_pipeworx for casual lookups.' Also notes additional cost, guiding when not to use.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds deep behavioral context: fan-out, blocking conditions, tradeability, resolution-rule risk, and safety notes. 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?

Very informative but verbose. Structured with sections, front-loaded with purpose. Could be more concise; some sentences are detailed but necessary for a complex 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?

No output schema, so description carries full burden. It thoroughly explains result shapes, resolver contract, parent event, news fields, and safety. Complete for a complex research tool.

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

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

Schema description coverage 100% sets baseline 3. Description adds examples, explains market input flexibility, depth options, and include_raw effect. Adds meaningful detail beyond schema.

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

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

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Specific verb+resource. Does not explicitly distinguish from sibling tools, but the scope is well-defined.

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 (should I bet, what data says, edge) and examples of blocking conditions (low confidence, closed markets). Lacks comparison to sibling tools but still strong guidance.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: it explains how off-calendar fiscal years are handled (AAPL Sep, NVDA Jan), that results are sorted by primary metric, and that it returns paired data with citation URIs. 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 front-loaded with example queries and key guidance (prefer over sequential lookups). It is somewhat lengthy but each sentence provides useful information. Could be slightly more concise without losing content, but structure is 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?

With no output schema, the description covers the return format (paired data + URIs) and sorting behavior. It addresses the two entity types comprehensively. However, it does not detail the exact structure of the paired data or mention pagination/truncation, which leaves some gaps for a complex tool.

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

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

The input schema already describes both parameters with 100% coverage. The description enhances this by explaining what data each type pulls (company: revenue, net income, cash, debt; drug: adverse events, FDA approvals, trial counts) and the expected format for values (tickers/CIKs for companies, names for drugs). This adds significant meaning beyond the simple enum and array descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, distinguishing it from sequential lookups. It specifies the verb 'compare' and the resource 'entities,' and provides example queries. The mention of specific data sources (SEC EDGAR/XBRL, FAERS) further clarifies the purpose.

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

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

The description explicitly advises to prefer this tool over sequential single-pack lookups when comparing entities. It provides example queries that signal when to use it. However, it does not explicitly state when not to use it (e.g., comparing more than 5 entities) or mention alternatives like entity_profile for single entities.

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, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: requires account (free with paid plan for thorough), returns findings packet with evidence, confidence, source, citation, and gaps[], and warns about empty results for non-structured topics.

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 every sentence adds value. It front-loads critical info (account requirement) and structures usage guidance clearly. Could be slightly more concise but effective.

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

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

Given the tool's complexity (multi-source parallel research) and absence of output schema, the description covers prerequisites, return format (findings packet with gaps), limitations (non-structured topics), and expected latency (15-60s). Complete for agent decision-making.

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

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

Schema coverage is 100%, but description adds meaning beyond enumerated values: explains depth enum (quick=3, standard=5 default, thorough=8 for paid) and clarifies that question can be broad/multi-part.

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

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

The description clearly states it performs grounded multi-source research across 1242 structured data sources, distinguishing it from open-web search and sibling tools like ask_pipeworx. The verb 'research' and resource 'structured data sources' are 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?

Explicitly states when to use (broad/multi-part questions over structured data) and when not to use (breaking current news, single lookup). Provides alternatives: ask_pipeworx for single lookups and current news.

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

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

Annotations already indicate readOnly, idempotent, nondestructive. Description adds that results include full schemas with examples and are ready to call, and the search returns top-N relevant tools.

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

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

Single paragraph but front-loaded with purpose and domain list, then usage guidance, then output details. Efficient and well-structured, though could be slightly more structured.

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

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

With no output schema, description fully covers return format (names, descriptions, schemas with examples) and states results are ready to call, sufficient for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples and clarifying that 'query' accepts aliases like task, q, search, description, and explains its natural language usage.

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific domains, distinguishing it from sibling tools that perform specific actions.

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 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use and implicit not-to-use guidance.

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

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

Annotations declare safe, idempotent read-only behavior; description adds details about fan-out across multiple sources, soft-fail for patents, and return structure. No contradictions.

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

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

Description is moderately long but well-structured with examples upfront. Every sentence adds value, though minor redundancy exists (e.g., repeating input constraints). Still clear and efficient.

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

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

Despite missing output schema, description fully explains return fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and limitations. Sufficient for agent to understand outputs.

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 enriches by explaining type enum (only 'company'), value format (ticker or CIK), and explicit exclusion of names. Adds meaning beyond schema.

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

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

Clearly defines tool as generating a holistic profile of US public companies, listing specific data sources and return fields. Distinguishes from siblings like resolve_entity by naming input constraints.

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 prefer this tool over chaining single-source lookups, and clarifies that names are not supported but resolve_entity should be used first. Provides concrete example 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 destructiveHint=true, and the description confirms 'Delete'. It adds context about clearing sensitive data, but no additional behavioral traits beyond what annotations provide. No contradiction.

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

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

Two sentences, no wasted words, front-loaded with core purpose. Every sentence earns its place.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description covers purpose, usage context, and sibling relationships completely.

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

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

Schema coverage is 100% and describes 'key' as 'Memory key to delete'. The description adds no further parameter meaning, 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 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It also distinguishes from siblings 'remember' and 'recall' by mentioning them.

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

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

Explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data' and pairs with 'remember and recall', providing clear context and alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which informs the agent of the exact process and output format without contradiction.

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

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

Three sentences: first for purpose, second for process, third for use cases. No unnecessary words, front-loaded with key information.

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

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

The description covers all necessary aspects: what it does, how it works, output format, and use cases. With no output schema, the description explicitly states the output is a 'single text blob', which is sufficient for a simple tool.

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

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

Schema description coverage is 100% with both parameters documented. The description does not add new meaning beyond the schema (e.g., default and max for max_links are already in schema). Baseline of 3 is appropriate.

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

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

The description clearly states 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by specifying the output format and use case.

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

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

The description lists explicit use cases (getting client's site indexed, drafting for own project, auditing competitor). It does not provide explicit exclusions or alternative tool references, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description aligns but adds no extra behavioral context beyond the structured data.

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

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

Single sentence, front-loaded with the key purpose, and 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 annotations and output schema presence, the description sufficiently explains the tool's return values and usage. Complete for a simple read 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 parameters are already documented. The description adds context by mentioning the key format and return contents, but does not compensate for any gaps.

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

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

The description clearly states the verb 'Get', resource 'full details for a Jira issue', and the specific parameter 'issue key'. It distinguishes from sibling tools like jira_search and jira_get_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?

While not explicit about when not to use, the description implies use when you have an issue key and need full details. Siblings like jira_search serve different purposes, so 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no contradictory information and mentions the return fields, which aligns with the non-destructive, idempotent nature. No additional behavioral details needed 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 one sentence, directly stating purpose and key details, with no extraneous information. Front-loaded and efficient.

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

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

For a simple, read-only, single-parameter tool with comprehensive annotations and an output schema present, the description is fully adequate. It mentions the returned fields and the input method, covering all needed context.

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

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

Schema coverage is 100% for the single parameter. The description adds an example ('PROJ') and clarifies that the parameter can be a key or ID, which adds slight value beyond the schema 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 the verb 'Get', the resource 'Jira project', and the method 'by key or ID'. It also lists the returned fields, distinguishing it from siblings like jira_get_issue or jira_list_projects.

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

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

The description implicitly indicates use for fetching a single project by key/ID, but does not explicitly mention when not to use or compare with siblings like jira_list_projects. Context from sibling names provides some guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true, covering safety and behavior. The description adds only the return fields (keys, names, descriptions, types) but doesn't disclose additional behaviors like pagination or rate limits. With rich annotations, a 3 is appropriate – the description adds some value but not extensive 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?

Two sentences with no wasted words. The first sentence states the purpose and return values; the second gives usage guidance. Information is front-loaded and efficient.

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

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

Given 0 parameters, comprehensive annotations, and an existing output schema, the description is complete. It covers the purpose, return fields, and a usage hint, which is sufficient for this simple tool.

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

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

The input schema has 0 parameters, so schema coverage is 100% trivially. Per guidelines, 0 params baseline is 4. The description does not need to explain parameters, and it adds no param info 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 action ('List all accessible Jira projects') and the resource ('Jira projects'), specifying the returned fields (keys, names, descriptions, types). It distinguishes from siblings like 'jira_get_project' which focuses on a single project and 'jira_search' which searches issues.

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 clear usage context: 'Use before searching to discover available projects.' This implies it's a preparatory step. While it doesn't explicitly state when not to use it, the context is sufficient for a simple listing tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns specific fields, which is helpful but not critical. No additional behavioral details like pagination or rate limits are provided.

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 with no unnecessary information. It front-loads the core functionality and uses straightforward language.

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 presence of an output schema and annotations, the description is sufficient. It provides a clear scope and the returned fields. No missing critical details for a simple search tool.

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

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

Schema coverage is 100% and all parameters have clear descriptions. The description does not add additional meaning beyond what the schema already provides; it only gives a high-level overview of what is returned.

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 'Search Jira issues using JQL queries' with specific returned fields (keys, summaries, status, assignee, priority). It distinguishes from sibling tools like jira_get_issue (single issue) and jira_list_projects (projects).

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

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

The description says 'Use to find tasks by project, status, assignee, or custom criteria' providing a clear use case. However, it does not mention when not to use this tool or compare it to alternatives like jira_get_issue for a single issue.

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, so the agent knows it's safe. The description adds that it returns specific fields and that inactive subscriptions are excluded by default. Without annotations, more behavioral details (e.g., pagination, rate limits) would be needed, but here it provides useful supplementary info.

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

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

The description is two sentences, front-loaded with the core purpose, then usage guidance. No unnecessary words, every sentence adds value.

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

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

For a simple list tool with a single optional parameter and no output schema, the description adequately explains the purpose, return fields, and usage. It lacks mention of pagination or ordering, but these are less critical for a tool likely returning manageable data.

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 single parameter 'include_inactive' is fully described in the schema (100% coverage). The description mentions 'active subscriptions' implying the default, but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like subscribe and unsubscribe by being the read counterpart.

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 advises using this tool to review monitored subscriptions before adding more or to find an ID for cancellation. This provides explicit context, though it could additionally state when not to use it (e.g., for creating or modifying subscriptions).

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 key behaviors beyond annotations: it sends feedback (write operation), is rate-limited to 5 per identifier per day, is free, and does not count against tool-call quota. Annotations are neutral (all false), so no contradiction; the description adds substantial context.

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

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

The description is a single concise paragraph of 7 sentences, front-loaded with the core purpose. Each sentence provides necessary information (use cases, types, restrictions, rate limits). Minimal waste, though slightly longer than strictly necessary.

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 (feedback submission), the description covers all needed aspects: purpose, use cases, restrictions, and behavioral notes. No output schema is needed; sibling tools are unrelated, so no further differentiation required.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds extra context by reiterating type meanings and instructing to describe issues in terms of tools/packs, which adds value beyond the schema.

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

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

The description clearly states the tool sends feedback about bugs, feature requests, data gaps, or praise to the Pipeworx team. It defines each type and specifies the action 'Tell the Pipeworx team,' distinguishing it from research or Jira tools 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?

The description explicitly lists when to use: for wrong/stale data (bug), missing tools (feature/data_gap), or praise. It also provides a negative example ('don't paste the end-user's prompt') and mentions rate limits and quota exemption, offering clear guidance.

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

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

Adds context beyond annotations: aggregated, no PII, cached, derived from analytics engine. No contradictions with annotations (read-only, idempotent, non-destructive).

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

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

Concise, well-structured with bullet points. Every sentence adds value without redundancy.

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

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

Sufficient for a simple read tool: covers what's returned, use cases, caching, and data source. No output schema, but description is clear enough.

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 describes parameter well (100% coverage). Description adds semantic value by explaining shorter windows surface hot items, longer show steady-state demand.

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

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

Description clearly states it returns trending tools/packs and call volume over a window, distinguishing it from siblings like ask_pipeworx or discover_tools by focusing on aggregate usage by other agents.

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

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

Explicitly lists three use cases (hot data sources, confirm canonical tool, align use case) and mentions caching window, providing solid guidance on when to use, though 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 declare read-only, open-world, idempotent, non-destructive. Description adds details about fill check, semantic anchor, partition filter, and response structure, providing comprehensive 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?

Well-structured with sections and bold for emphasis, but slightly verbose. Still, 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?

No output schema, but description fully explains response structure (opportunities array, partition_check object) and edge cases like semantic anchor, partition filter, and fill check. Complete for an agent to use correctly.

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

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

Both parameters have schema descriptions, and the tool description adds rich context: event slugs examples, topic as seed question, and how each parameter changes execution mode. 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 it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on specific detection methods.

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

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

Explicitly tells when to use NO args for trending_scan, event for single-event mode, topic for cross-event mode, with recommendations. Also advises using polymarket_fill_risk for custom sizing, providing clear context and alternatives.

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

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

The description discloses extensive behavioral traits beyond annotations: caching at KV level (1h), three response segments, diagnostics for empty results, Fed bets' special handling, and detailed model formulas. Annotations already indicate read-only, open-world, idempotent, and non-destructive, and the description reinforces and adds context.

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

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

The description is long but well-structured with clear segments, formulas, and bullet-like explanations. It front-loads the purpose and then details each model. Every sentence adds value, though some could be streamlined for faster scanning.

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 (9 parameters, 3 model families, diagnostics, caching), the description is fully complete. It explains return values (by_segment, fed_candidates, diagnostics) and parameter interactions, compensating for the lack of an output schema.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond field descriptions: it explains knobs as 'tradeable-edge filters', clarifies the relationship between min_kelly and min_partition_leg_kelly, and provides concrete examples (e.g., 'Set to 5000 to drop thin-book opportunities').

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the use case "what should I bet on today" and distinguishes from siblings via specific model families and the edge-finding purpose.

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

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

The description provides explicit guidance on when to use the tool (discovering edge opportunities) and explains tradeable-edge knobs like min_liquidity and max_spread_pp. However, it does not explicitly compare to siblings or state when not to use it.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: explains response structure (tracked, expired, snapshot_dates), data sources, cache-miss gaps, and limits (60-day TTL, daily closes). 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 and front-loaded with the core purpose. However, it is somewhat verbose, especially in the response details. Still, every sentence earns its place given the tool's complexity.

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

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

Given no output schema, the description fully explains the return types (tracked, expired, snapshot_dates) with fields and meaning. It covers edge cases like gaps and TTL. No gaps in context.

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

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

Schema coverage is 100%. The description adds context beyond the schema: clarifies 'days' as lookback with default and range, and 'window' as snapshot family with examples. This helps an agent understand parameter usage beyond just types and defaults.

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

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

The description clearly states the tool provides 'Edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes itself from siblings like polymarket_edges and polymarket_arbitrage by focusing on time-series analysis.

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

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

The description provides strong guidance on when to use the tool, e.g., comparing a fresh wide edge to an old one. It lacks explicit alternatives or when-not-to-use, but the context is sufficient for an AI agent.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds critical behavioral context: it walks the order-book ladder, returns specific fields (vwap_fill_price, slippage, verdict), and warns that partial basket fills create unhedged directional positions—a dominant loss mode. 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 clear headings for each mode, front-loaded with the core purpose, and every sentence adds essential detail. While verbose, the complexity of two modes justifies the length; there is no wasted text.

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 has no output schema, so the description must cover return values. It lists all key outputs for both modes (top_of_book, vwap, slippage, verdict for single-market; theoretical_sum, capture_ratio, profit_usd, forced_directional_risk for basket). This provides an agent with sufficient information to interpret results and make decisions.

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

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

Schema coverage is 100%. The description adds significant value by explaining parameter behaviors across modes: size_usd interpretation differences (spend vs notional), the clamp range, and the auto default for side in basket mode. This goes beyond the schema's concise descriptions.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live order-book depth, and distinguishes between single-market and basket modes. It explicitly ties to sibling tools polymarket_arbitrage and polymarket_edges, providing differentiation and usage context.

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

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

The description contains explicit 'USE THIS' instruction before acting on specific signals, explains the risks (partial fills, directional exposure), and covers both modes with prerequisites (market or event slug). This provides strong guidance for when and why to invoke the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds substantial behavioral context: it discloses that the tool filters non-equivalent bet shapes, provides safety fields like compatibility_warning and temporal alignment, and explains skipped_cross_type/counters. 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 quite long but well-structured, with clear sections for modes, response, and safety fields. It is front-loaded with the core purpose. Some redundancy could be trimmed, but the length is justified by tool complexity.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, etc.). It covers what an agent needs to interpret results, making it complete for effective 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% with good parameter descriptions. The description adds extra semantic value by explaining the two modes (topic vs explicit) and how explicit parameters override topic mappings, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It explains two operational modes and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explicitly provides guidance on when to use topic shortcuts vs explicit tickers, and warns that most pre-mapped topics currently return compatibility warnings, setting realistic expectations. It also explains the conditions for compatibility_warning and temporal alignment, helping agents avoid misuse.

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. Description adds scoping context but no additional behavioral traits (e.g., rate limits, side effects).

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 efficient sentences, front-loaded with purpose, no wasted words, clear structure.

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

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

Adequate for a simple tool with one optional parameter and safety annotations; return value is implied but not explicitly described. Could improve with brief note on output format.

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

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

Schema coverage is 100% and schema already describes parameter. Description reinforces usage (omit for list) and adds concrete key examples, adding value beyond schema.

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

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

Description clearly states verb (retrieve/list) and resource (value/key saved via remember), and distinguishes from siblings like remember (save) and forget (delete).

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

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

Provides examples of when to use (user's target ticker, address, research notes) and scoping (by identifier), though lacks explicit 'when not to use' or alternative tools.

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

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

Description states that setting mark_read:true flags events as read, which is a state change. However, annotations declare readOnlyHint=true, indicating no state modification. This is a direct contradiction, forcing a score of 1 per rubric.

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

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

Three concise sentences, no fluff, front-loaded with purpose and then key details. Every sentence earns its place.

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

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

Explains what is returned (source, citation_uri, raw payload) and provides an alternative access method. Lacks pagination or error handling, but given no output schema and simple tool, it is fairly complete.

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

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

Schema coverage is 100% with parameter descriptions, and the description adds valuable context: examples for type ('sec_8k'), format for since (ISO timestamp), and the effect of mark_read on subsequent calls. Enhances understanding beyond schema.

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

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

The description clearly states 'Pull fired events from your subscription feed', specifying the action and resource. It details the return fields (source, citation_uri, raw payload) and distinguishes itself from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit filtering guidance ('Filter by type and/or since'), explains how mark_read works to ensure subsequent calls show only newer events, and mentions polling suitability and an alternative REST endpoint. Lacks explicit when-not-to-use or alternatives among siblings.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail, and return structure with citation URIs. Lacks rate limit details but still strong.

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 front-loaded examples and technical details later. Each sentence adds value, though slightly verbose for a single 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?

No output schema, but description explains return format (grouped changes, total count, URIs). Covers USPTO limitation and sibling differentiation. Completeness is good given 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 all parameters (100% coverage). Description adds context: 'since' accepts ISO or relative shorthand, 'value' can be ticker or CIK, and recommends '30d'/'1m'. Adds meaningful examples.

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

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

The description clearly states the tool returns a change feed for a company (SEC filings, news, patents) and explicitly contrasts with the sibling entity_profile for static profiles. Uses specific verbs and resources.

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 query examples, explains when to use (change feed) and when to use entity_profile instead. Offers guidance on typical 'since' values like '30d'.

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 idempotentHint=true (safe to repeat) and destructiveHint=false. The description adds behavioral details beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This fully discloses session-dependent persistence and scoping. 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 concise: four sentences, front-loaded with the core purpose, followed by usage guidance, then behavioral details. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (two required string params, no output schema), the description covers all essential aspects: purpose, when to use, parameter semantics (implicitly), persistence behavior, scoping, and relationship with sibling tools. No gaps.

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

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

Schema coverage is 100%, so the input schema documents both parameters (key, value) with descriptions. The tool description does not add parameter-specific details beyond restating 'key-value pair' and examples in usage guidelines. Baseline 3 is appropriate as the schema adequately covers parameter meaning.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later — across this conversation or across sessions.' It specifies the verb (save), resource (memory key-value pair), and scope (cross-session). It also differentiates 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?

The description provides explicit when-to-use guidance: 'when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject).' It mentions pairing with recall and forget, though it does not explicitly state when not to use the tool. The context is strong but missing a clear exclusion.

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 the behavioral detail that each call cascades through several lookup endpoints internally, which is useful context beyond the annotations. No contradictions.

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

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

The description is relatively concise given the complexity, using a question-answer style to front-load purpose. It packs detailed type information efficiently. Minor verbosity could be trimmed, but overall well-structured.

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

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

Without an output schema, the description sufficiently explains return values for both types. However, it omits error handling (e.g., what happens if entity not found) and does not specify if multiple matches are possible. Still, for a resolver tool, it provides adequate completeness.

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

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

Schema coverage is 100% but the description adds substantial meaning: it explains the return values per type (e.g., company returns ticker + CIK + name + citation URI), and details accepted input formats (ticker, CIK, name). This significantly enriches the schema definitions.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples ('ticker for', 'CIK for', 'RxCUI for'). It differentiates itself from siblings by positioning as the go-to tool for name-to-ID lookups, contrasting with other tools like entity_profile or compare_entities.

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

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

Explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also implies when not to use by focusing on ID resolution, and mentions it replaces manual multi-step lookups, clarifying its role relative to alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: it probes each entity, returns a ranked list with score, confidence, and signal density. This supplements the annotations with additional output details.

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

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

The description is three sentences long, front-loading the core function and process without redundancy. Every sentence adds value: purpose, method, use case, and output.

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 lack of an output schema, the description adequately describes the return format (ranked list with score, confidence, signal density) and explains the subject treatment. It is complete enough for an agent to understand what the tool does and what it returns.

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

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

Input schema has 100% coverage with descriptions. The description adds meaning beyond the schema by noting that the first entity is treated as the 'subject' for narrative, which guides usage. This extra context justifies a score above the baseline 3.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It uses specific verbs and resources, and distinguishes itself from the sibling tool ai_visibility_check which handles single entities.

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

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

The description provides clear usage context ('competitive AI-marketing audits') and an example question. It implies when to use this tool over alternatives (e.g., single vs. multi-entity comparison) but does not explicitly state when not to use it.

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

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

Beyond annotations (readOnly, idempotent), the description discloses composite nature, fan-out across services, potential 5-30s latency for bundlephobia first measurement, and graceful partial failure with 'sources_failed' field.

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?

Packed with information but well-structured. Front-loaded with purpose, then details. Could be slightly more concise but no waste.

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

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

Despite no output schema, the description enumerates return fields exhaustively (summary block, per-advisory detail, links, alternative versions). Covers partial failures, ecosystem scope, and latency, making it complete for a complex tool.

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

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

Schema coverage is 100% but description adds context: scoped packages accepted for 'package', default behavior for 'version' (omission defaults to latest). Adds marginal value beyond schema.

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

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

The description clearly states the verb+resource: a composite 'should I add this npm package to my project' check. It distinguishes from sibling tools by focusing on npm dependency analysis, contrasting with other tools like Jira, AI visibility, etc.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also specifies exclusions: NPM ecosystem only; PyPI etc. fall under deps.dev:version directly, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, establishing the safety profile. The description significantly adds: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation flag. This goes well beyond annotations.

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

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

Single focused paragraph. Front-loaded with the core purpose, then expands with technical details and use case. Every sentence adds value without redundancy. No filler.

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

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

For a complex tool (semantic search, embeddings, windowing, truncation), the description covers all necessary aspects: what it does, how it works (algorithm details), limits (200K chars), output features (offsets, similarity scores), and relationship to a sibling tool. Despite no output schema, the description compensates with sufficient detail about return values.

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's job is to add value beyond the schema. It does: explains 'text' as document text, 'limit' with range (1-20, default 5), and provides natural-language query examples that illustrate usage. While schema already describes each parameter, the description makes their purpose and constraints clearer.

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

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

The description clearly identifies the tool's purpose: semantic search within a previously fetched record. It gives concrete use cases (SEC 10-K, article) and specific output features (top-N passages with offsets and similarity scores). It distinguishes from sibling tools by mentioning ask_pipeworx_grounded, showing a clear differentiation.

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

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

Explicitly states when to use the tool: 'when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter'. It also describes how it pairs with ask_pipeworx_grounded, providing clear guidance on tool 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 adds significant behavioral context beyond annotations: requires OAuth, returns new ID, SMS daily cap of 10, webhook auto-disabled after 10 consecutive failures, and that webhook secret is returned once. No contradiction with annotations (readOnlyHint false, etc.).

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

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

The description is long but every sentence adds value. It is front-loaded with the purpose and well-structured with sections for types and delivery channels. Could be slightly more concise, but overall efficient.

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

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

Given the complexity (multiple types, nested params, delivery options) and no output schema, the description is thorough: covers prerequisites, type-specific filters, delivery constraints, return value, and failure behavior. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, yet the description enriches all parameters: explains each enum value with examples, provides detailed object structures for params and delivery, and adds constraints like E.164 phone and rate limits. Goes well beyond the schema.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation and returning a subscription ID.

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

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

Clearly states the requirement for a Pipeworx OAuth account, noting that anonymous and BYO cannot persist subscriptions. Provides examples for each type and mentions delivery channels and their constraints. However, it does not explicitly exclude when not to use, 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 declare readOnly, openWorld, idempotent. Description adds that it returns category-bucketed example questions with tool+argument shapes, draws from live catalog. No contradictions. Discloses functional behavior 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 front-loaded example queries, clear instructions, and list of categories. Slightly long but every sentence adds value. No redundancy.

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

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

Given single optional parameter and no output schema, description adequately explains return format (category-bucketed example questions with tool+argument shape) and usage. Sufficient for an onboarding 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 100% with one optional parameter 'topic'. Description adds value by listing exact focus areas (finance, pharma, etc.) and explaining that omission gives cross-category spread, which is not in schema 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?

Clear verb+resource: 'suggest_questions' as onboarding entry point. Distinguishes from siblings by positioning as the first tool to call when unsure what Pipeworx can do. Provides specific examples and mentions it returns exact tool+argument shape.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Mentions optional topic parameter for focus. Does not explicitly state when not to use, but implication is clear.

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

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

The description explains that the row is deactivated, not deleted, aligning with destructiveHint=false. It also mentions ownership enforcement, which goes beyond annotations. No contradictions with annotations.

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

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

Two concise sentences that front-load the purpose and include important behavioral details. No extraneous information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers all essential aspects: what it does, ownership, and the deactivation behavior.

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

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

The schema has 100% coverage with a clear description for the id parameter. The description adds useful context that the id is returned by subscribe, aiding in correct usage.

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

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

The description clearly states the action (Cancel), the resource (subscription), and the method (by id). It adds nuance about ownership enforcement and deactivation, distinguishing it from related 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 provides context on ownership and side effects, but does not explicitly state when to use this tool versus alternatives or when not to use it. However, the context is sufficient given the sibling list.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context such as the return format (verdict, citation, delta) and the fact that it replaces 4–6 sequential calls, enhancing transparency beyond annotations without contradiction.

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

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

The description is moderately detailed but efficiently front-loaded with keywords and examples. Every sentence serves a purpose, though some redundancy exists (e.g., multiple verb examples). It earns its length without being overly verbose.

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

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

Given the tool's complexity and lack of output schema, the description adequately covers purpose, domain, input, and return fields. It mentions limitations ('v1 supports company-financial claims'), which helps set expectations. Slightly more detail on edge cases or unsupported claim types would improve completeness.

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

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

The input schema has 100% coverage for the single required parameter. The description provides concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion') that clarify expected input format and scope, adding meaning beyond the schema's brief description.

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

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

The description clearly states it verifies natural-language claims, specifically company-financial claims, using SEC EDGAR + XBRL. It provides example queries and distinguishes itself from siblings by mentioning it replaces multiple sequential calls, 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?

The description advises using the tool whenever the agent needs to check factual correctness of a claim and specifies the supported domain (company-financial claims). It does not explicitly state when not to use it or list alternative tools, but the context is clear enough for appropriate selection.

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