Jira

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses that probing Anthropic requires a BYO API key with direct user payment, default model is free, and return format includes per-model and combined views. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph of three sentences. It front-loads the primary action, then covers details and use cases, with no redundancy or 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 tool with no output schema, the description adequately explains the return format (per-model score, confidence, signals, raw_response + combined view) and use cases. It lacks detail on 'signals' and the combined view structure, but annotations provide safety context.

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

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

Schema description coverage is 100% and adequately describes each parameter. The description adds minor value (e.g., default model name, _apiKey passthrough) but does not significantly extend schema info.

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 probes LLMs for knowledge about a business/product/topic and returns a visibility score. It distinguishes itself from sibling tools like scan_competitor_ai_presence and ask_pipeworx by focusing on AI visibility metrics.

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 use cases (AI-marketing audits, pre-launch checks) but does not explicitly guide when to use this tool vs alternatives or when not to use it. No exclusion criteria or alternative tool references.

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, and destructiveHint=false. The description adds value by explaining the routing mechanism, the scale of sources, the citation URIs, and the 'one fast call' performance characteristic. It does not contradict the annotations and adds sufficient behavioral context for a non-destructive QA tool.

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, front-loaded with the 'PREFER OVER WEB SEARCH' directive, then explains the mechanism, provides usage triggers and examples, and ends with escalation paths. Although lengthy, every sentence serves a purpose and the organization makes it easy to scan.

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 as a routing/QA meta-tool, the description is remarkably complete: it covers what it does, when to use it, when not to use it, alternatives, output format (structured answer with citations), performance ('one fast call'), and scope ('works on every tier'). No output schema exists, but the description effectively communicates the return value.

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

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

The input schema has 100% description coverage, with all parameters being aliases for 'question' and clearly documented. The description reinforces the natural-language format via examples but does not add new parameter syntax or format details beyond what the schema already provides, so the 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 what the tool does: it routes a factual question to the right source among 5,529 tools across 1,455 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research and explaining when to step up.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases ('what is', 'look up', 'find', etc.), gives concrete examples, and states it is the default entry point. It also includes clear when-not-to-use instructions by pointing to alternatives for hallucination-resistant answers and broad/multi-part questions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds that candidate routing improvements are enabled live when under test, that no candidate is currently active, and that it is a full working router rather than a stub. This is valuable experimental 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 condense all essential information: beta status, current state, usage guidance, and reassurance that it is a full router. Every sentence earns its place 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?

The description covers purpose, usage, current experimental state, and response shape (via 'same response shape'), which is sufficient given the schema and annotations. No important context is missing.

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 6 parameters are documented in the schema). The description adds 'same arguments' but doesn't need to elaborate further, so the baseline of 3 applies.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes from the sibling ask_pipeworx by highlighting the experimental candidate routing improvements.

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 to 'use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. This provides clear when-to-use guidance and implies the stable alternative.

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

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

The description discloses behavioral traits well beyond the annotations: it routes to other tools, extracts only from tool results, returns explicit refusals with specific reasons, and incurs an additional LLM call. It fully details the success and refusal response schemas, which is especially valuable given the lack of an output schema.

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

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

Every sentence earns its place: mode definition, routing mechanism, response shape, usage criteria, and cost trade-off are each covered in a compact, front-loaded format. No filler or redundant information.

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

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

Despite having no output schema, the description completely specifies return values, refusal reasons, cost implications, and usage context. It gives the agent all necessary information to select and invoke the tool correctly, including when to choose the lighter alternative.

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

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

The schema already covers 100% of parameters with clear aliases (q, text, input, query, prompt, question) and descriptions, so the description need not repeat parameter details. The baseline of 3 applies because the description adds no parameter-specific semantic value, but the schema is fully sufficient.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb and resource. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded extraction, evidence, and refusal behavior.

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?

Usage guidance is explicit: use when answers will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts and legal claims. It also provides an exclusion by preferring ask_pipeworx for casual lookups due to the extra LLM call cost.

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

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

Description goes far beyond annotations, detailing market match confidence, cancellation rules, short-circuiting behavior, news fallback, and wide-spread handling. All annotations (readOnlyHint, etc.) are consistent and supplemented with critical behavioral context.

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

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

Description is lengthy but well-structured with clear sections and front-loaded purpose. Every sentence adds value for a complex tool. Minor deduction due to length, but justified by 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?

No output schema, yet description comprehensively covers return values (result.market, result.analysis, result.evidence) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Complete for the tool's complexity.

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

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

Schema coverage is 100%, and description adds significant meaning: explains how 'market' can be slug, URL, or question text; clarifies 'depth' values and 'include_raw' impact on response size. Provides examples and default behavior.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and gives use cases ('should I bet on X'). It distinguishes from sibling tools like polymarket_edges by focusing on specific bet research.

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

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

Explicitly says when to use the tool (e.g., 'should I bet on X'). Provides concrete examples but does not explicitly state when not to use it or list alternative tools. However, given the context and sibling list, usage is well implied.

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

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

Description adds rich behavioral details beyond annotations: it pulls data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years correctly, and for drugs uses FAERS data. Annotations already indicate read-only, idempotent, open-world, and non-destructive, which align. 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 well-structured: purpose first, then usage examples, then data source details. It's somewhat dense but every sentence contributes. Slightly longer than necessary but not excessively wordy.

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

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

Despite no output schema, the description explains the return format (paired data + citation URIs) and that results are sorted by primary metric. Given the tool's complexity and full schema coverage, this is complete for an AI agent to understand the tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by providing concrete examples (e.g., ['AAPL','MSFT'] for companies, ['ozempic','mounjaro'] for drugs) and explaining the 2-5 limit, but the schema already covers the basics.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific metrics for each type (e.g., revenue, net income for companies). It distinguishes itself from sequential single-pack lookups, which are slower.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance. Example queries like 'rank these companies' help. It doesn't explicitly mention when not to use (e.g., more than 5 entities) or alternatives like entity_profile for single entities, but the schema limits are implied.

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 substantial behavioral detail beyond annotations: account requirements, paid plan for thorough depth, parallel dispatch to 5,529 tools, return packet composition (verbatim evidence, confidence, source, fetched_at, citation), explicit gaps[] behavior with never-invented guarantee, contradictions[] for standard/thorough, hop field, citation_uri fetchability caveat, semantic excerpting, and latency estimates. Annotations cover read-only/idempotent, so this is all additional value.

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

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

Front-loaded with critical account prerequisite and fallback tool, then proceeds from core function to usage guidance to output details. Every sentence carries useful information, but the description is quite long. It is appropriately sized for the tool's complexity, yet could be slightly trimmed without losing substance, so not a perfect 5.

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

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

Without an output schema, the description fully explains the return format: findings packet with evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[], and semantic excerpting. It also covers auth, pricing, use-case boundaries, and latency, making it complete for an agent to correctly invoke and interpret results.

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

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

Schema already provides 100% coverage: question is described as natural language with broad/multi-part acceptable, and depth has full enum explanations for quick/standard/thorough. The description reinforces these semantics with examples and process context, but does not add new parameter-level information beyond the schema, so baseline 3 applies.

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

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

Description clearly states it performs grounded multi-source research across 1455 STRUCTURED data sources in one call, explicitly distinguishing itself from open-web search and single-lookup tools. The verb 'research' plus resource 'structured data sources' and the contrast with ask_pipeworx makes its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also includes an account fallback instruction: if not signed in, use ask_pipeworx instead.

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

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

Annotations already declare the tool is read-only, idempotent, and non-destructive. The description adds behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This clarifies the output format and the fact that multiple aliases are accepted for the query parameter.

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. The list of domains is helpful for an agent to understand scope but makes the description slightly longer. Overall, it is concise and every sentence adds value.

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

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

Given that there is no output schema, the description fully explains the return value: tools with names, descriptions, and schemas. It also covers the tool's scope (various domains) and usage guidance. No gaps are apparent.

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 doesn't need to compensate. However, the description adds value by stating that the query accepts natural language descriptions and listing example queries in the schema examples. It also clarifies that 'task', 'q', 'search', and 'description' are aliases for query.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many example domains and explicitly distinguishes itself from sibling tools by saying 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description specifies when to use: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by concrete domains. It also advises 'Call this FIRST' as a default action. While it doesn't list explicit alternatives, the context implies using direct tools if the agent already knows what to call.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=True. Description adds: fans out across multiple sources, returns specific fields (cik, filings with URIs, fundamentals sorted), patents soft-fail, and GDELT→GNews fallback. No contradictions; adds useful behavioral context beyond annotations.

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

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

Description is moderately long but front-loaded with example queries and key guidance. Each sentence serves a purpose (use cases, preference, source list, caveats). Could be slightly more concise, 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?

Given tool complexity (multiple sources, no output schema), description adequately covers return fields (cik, filings, fundamentals, patents, news, LEI) and caveats (patents sunset, name unsupported). Provides enough information for an agent to understand and use the tool correctly.

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

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

Input schema already covers both parameters fully (100% coverage) with descriptions for type ('Only company supported') and value ('Ticker or zero-padded CIK'). Description reiterates that names not supported but adds minimal new meaning. 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?

Description clearly states 'full cross-source profile of a US public company' with specific examples like 'tell me about X' and lists return fields. It distinguishes from siblings by emphasizing 'ALWAYS PREFER over chaining single-pack lookups' and references resolve_entity for name resolution.

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

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

Explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. Provides clear context for 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?

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but does not describe additional behavioral traits beyond what annotations cover. No contradictions.

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

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

The description is concise with two sentences: first defines purpose, second provides usage guidelines. No unnecessary words, front-loaded.

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

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

Given the simple single-parameter schema and clear annotations, the description covers purpose, usage, and behavioral context. No output schema is needed for a deletion tool; the description is 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% and the parameter 'key' is described as 'Memory key to delete'. The description adds 'by key' but provides no additional 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 deletes a memory by key, using the verb 'Delete' with the resource 'memory'. It distinguishes from siblings 'remember' and 'recall' by specifying it is for clearing stale or sensitive data.

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

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

The description explicitly provides usage guidelines: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also pairs with 'remember' and 'recall', implying 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 a safe, idempotent, read-only operation. The description adds valuable behavioral details: it fetches the page, extracts specific elements (title, description, key links), and outputs a standard markdown format. This goes beyond the annotations and helps the agent understand the exact process and output.

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-loaded with the core action, and every sentence adds value without redundancy. It is efficiently structured and easy to parse.

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

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

Given the tool's simplicity (2 parameters, no output schema, rich annotations), the description covers all necessary aspects: purpose, behavior, usage examples, and output format. There are no gaps in understanding how to use the tool or what it produces.

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 provides descriptive text for both parameters (url and max_links), including default and max for max_links. The description does not add any new semantic information beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the target 'any URL'. It distinguishes from sibling tools by specifying the exact output format and use case, which is unique among the listed 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 lists three concrete use cases (client site indexing, own project drafting, competitor auditing), which clearly indicate when to use the tool. However, it does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds value by detailing the returned content (e.g., comments, attachments), which is behavioral context beyond what annotations provide. No contradictions.

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

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

The description is a single informative sentence with no fluff. It could slightly benefit from structuring the returned fields as a list, but it remains efficient and front-loaded with the key action.

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

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

Given the tool's moderate complexity (2 parameters, multiple return fields) and the presence of an output schema, the description sufficiently covers what the tool does and what information it returns. It is complete enough for an agent to understand without needing to inspect the 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% with both parameters described. The description adds examples and clarifies that the 'fields' parameter is optional and comma-separated, providing semantic guidance beyond the schema's bare 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 action 'Get full details for a Jira issue by key' and lists the returned fields (description, status, assignee, priority, comments, attachments, linked issues). It distinguishes itself from siblings like jira_search and jira_get_project by focusing on a single known issue.

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

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

The description implies usage when you have an issue key and want full details. It does not explicitly provide when-not-to-use or alternatives, but the context of sibling tools and the 'by key' phrasing gives sufficient guidance for an agent to select this tool over others.

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 no destructiveness. Beyond these, the description adds that it returns specific fields (name, description, lead, etc.), providing useful behavioral context. No contradictions.

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

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

The description is a single sentence that directly states the tool's purpose and output, with no extraneous content.

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

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

Given the simple input (one required parameter) and the presence of an output schema, the description sufficiently covers what the tool does and what it returns. No additional context needed.

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

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

Schema coverage is 100%, with the schema describing project_key as 'Project key (e.g., "PROJ") or numeric project ID'. The description repeats this example ('e.g., PROJ'), adding minimal extra meaning. 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 retrieves details for a specific Jira project by key or ID, listing return fields (name, description, lead, issue types, custom fields). This distinguishes it from siblings like jira_list_projects and jira_get_issue.

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

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

The description specifies the input method (key or ID) and implicitly indicates use when a known project's details are needed. However, it does not explicitly mention when not to use or alternatives, though 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=true, idempotentHint=true, destructiveHint=false. Description adds that it returns project details, but beyond that does not expand on behavioral traits (e.g., pagination, rate limits).

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

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

Two efficient sentences: first declares action and output, second provides usage guidance. No extraneous words; each 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?

With no parameters, complete annotations, and an output schema, the description is fully sufficient. It covers purpose and usage, leaving no gaps.

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

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

No parameters (0 params, 100% schema coverage), so baseline is 4. Description does not add parameter details as none exist, but it does describe output, which is acceptable.

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 'List all accessible Jira projects' and specifies returned fields (keys, names, descriptions, types). This distinguishes from sibling tools like jira_get_project (single project) and jira_search (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?

Explicitly says 'Use before searching to discover available projects,' providing a clear when-to-use context. However, it does not explicitly state when not to use or mention alternatives, missing the highest bar.

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, and idempotentHint=true, covering safety and idempotency. The description adds that it returns specific fields (keys, summaries, status, assignee, priority), which is useful but partially redundant with the schema examples. No contradictions or additional behavioral quirks are needed.

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

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

Two clear, front-loaded sentences with no extraneous information. Every sentence adds value: first defines action and resource, second clarifies return fields and use cases.

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 thorough annotations and an output schema (implied), the description sufficiently covers purpose, usage, and return data. No missing critical details for a search tool.

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

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

The input schema has 100% coverage with descriptions for all three parameters (jql, fields, max_results) and includes helpful examples. The description merely reiterates that results include certain fields, adding minimal new value beyond the schema. Baseline 3 is appropriate given schema richness.

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

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

The description clearly states the tool searches Jira issues using JQL queries, which is specific and distinct from sibling tools like jira_get_issue (single issue retrieval) and jira_list_projects (project listing). It covers the scope of searching by project, status, assignee, or custom criteria.

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

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

The description explains when to use the tool (search tasks by criteria) but does not explicitly mention when not to use it, such as for retrieving a single issue. However, the existence of sibling tools provides implicit guidance, and the description itself is clear enough to 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, idempotentHint, and destructiveHint. The description adds that it returns a set of fields and that inactive subscriptions are excluded by default (with an optional parameter). This is valuable beyond annotations.

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

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

Two sentences, no fluff. First sentence states purpose and output fields; second gives usage guidance. Front-loaded with essential info.

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 single parameter, rich annotations, and list of return fields provided in the description, the description is complete for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so the schema fully describes the single parameter. The description does not add parameter semantics beyond what the schema provides, which is acceptable but not exceptional.

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 ('List'), resource ('the caller's active subscriptions'), and provides a list of return fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context and implies when not to use (not for subscribing/unsubscribing).

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

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

Annotations are all false, so the description carries the transparency burden. It discloses the claim_token flow, daily rate limit (5 per identifier per day), that it's free and doesn't consume quota, and that the team reads digests daily. It also explains how to check resolution status with claim_token, adding behavioral detail well beyond the annotation flags.

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

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

The description is a single dense paragraph of ~170 words, but it is front-loaded with the purpose in the first sentence and every subsequent sentence delivers a distinct fact (types, exclusions, token flow, rate limits). While not broken into bullets, it is efficiently packed without redundant 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 feedback tool with no output schema, the description covers all essential context: purpose, trigger conditions, exclusion boundaries, token-based follow-up mechanism, rate limiting, and how feedback is consumed. It even gives a concrete example of a claim_token format. This is a complete and self-contained explanation.

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

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

Input schema has 100% coverage with descriptions for every parameter, providing the baseline of 3. The description adds meaningful extra semantics: it explains the claim_token lifecycle (filing without an account returns one, passing it back retrieves status), and instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which supplements the message parameter schema.

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

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

The description opens with a clear action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and differentiates from siblings by focusing on feedback about Pipeworx tools, not asking questions or research. The enumerated types (bug, feature, data_gap, praise) further clarify its scope.

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

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

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when something worked surprisingly well') and when not to ('if the tool came from a different MCP server... file it with that server instead'). It also provides a disambiguation rule based on tool name source, which is strong alternative guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds crucial behavioral details: caching (5min-1h), data source (CF analytics-engine), no PII, and self-aggregating nature, going beyond annotations.

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

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

Three sentences with no fluff. The main result is stated immediately, use cases are bulleted, and technical details are appended succinctly. 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?

Despite no output schema, the description explains what is returned (top tools, packs, volume) and covers data origin, caching, and privacy. For a tool with one optional parameter, this is thorough.

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

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

Schema coverage is 100% with a clear enum and description for the single parameter. The description adds extra context on window semantics (hot vs steady-state) and defaults, which enhances 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 that the tool returns top tools, top packs, and total call volume over a window. It uses specific verbs and resources, distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

Three explicit use cases are listed, covering discovery, confirmation, and alignment. The description also explains when to use different window durations (shorter for hot, longer for steady-state), providing clear guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: semantic similarity threshold (≥0.30 Jaccard), partition placeholder filter (>20% returns null), and live book depth fill check. 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 long but well-structured with clear sections. Every sentence provides useful information. However, it could be slightly more concise; some details like SEMANTIC ANCHOR and PARTITION FILTER could be integrated more tightly.

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

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

Despite no output schema, the description thoroughly documents response fields (opportunities[], partition_check, suggested_trade, fill_check). It also covers edge cases (placeholder filtering, low similarity) and mentions polymarket_fill_risk for custom sizing. Highly 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% with descriptions for both event and topic parameters. The description significantly adds value: provides concrete examples like 'fed-decision-may-2026' and explains that topic accepts seed questions. It clarifies mode selection and behavior beyond schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for specific market, topic for cross-event scan. This clearly differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan of the top ~200 markets', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also includes fill check instructions and warns when not to trade based on realizable_edge_pp ≤ 0.

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 details beyond annotations, including caching (1h at KV level keyed on all knobs), response structure (by_segment, diagnostics), treatment of Fed bets (excluded from ranking), and model families. Annotations already declare readOnlyHint, and the description aligns 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 front-loaded with a clear purpose statement but becomes verbose with detailed model descriptions. While well-structured with sections and bullet points in text, it could be more concise for an agent to parse quickly. Every sentence adds value, but the length may be overwhelming for simple use cases.

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

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

The description is highly comprehensive given the tool's complexity, 9 parameters, and no output schema. It covers response structure, caching, empty segment diagnostics, and parameter interactions. Minor gaps include lack of explicit return type specification, but overall it provides sufficient context for effective agent usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by grouping parameters under 'tradeable-edge knobs' and explaining their combined effect, but it does not add significant new semantic detail beyond what the schema already provides for individual parameters.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly identifies the verb 'scan' and resource 'Polymarket markets' and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge discovery from Pipeworx disagreement.

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

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

The description specifies the use case ('what should I bet on today') and implies agents should use this for discovering opportunities without paging hundreds of markets. It mentions tradeable-edge knobs but does not explicitly contrast with sibling tools or state when not to use it, which would be ideal for a 5.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it explains the data source (daily snapshots), output structure (tracked, expired, snapshot_dates), and limitations (60-day TTL, gaps). No contradiction with annotations.

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

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

The description is detailed but slightly long. It front-loads the key question and then provides structured output details. Every sentence adds value, though some minor redundancy exists. Efficient for the complexity.

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

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

Given no output schema, the description fully explains the return format (tracked, expired, snapshot_dates) with field meanings. It covers data limitations (TTL, snapshots start, gaps) and edge cases, making it self-contained for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats parameter info: days (lookback default 14, max 30) and window (default '1wk'), adding minimal extra meaning. It does not provide new semantic depth beyond what the schema already states.

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: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?'), which distinguishes it from sibling tools like polymarket_edges.

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

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

The description gives context on when to use the tool (e.g., to differentiate between a fresh wide edge and a 3-week-old one). It does not explicitly state when not to use it or name alternatives, but the purpose and data limitations (TTL, snapshot start) provide clear guidance.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description aligns fully, characterizing the tool as a risk check with no side effects. Adds valuable context on real-world failure modes (thin books, unhedged risk) not evident from annotations alone.

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

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

While the description is long, it is well-structured with clear headings for single-market and basket modes, and enumerates return fields and warnings. A minor improvement could be further condensing some explanations, but the density of useful information justifies the 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, the description fully covers inputs, behavior, and outputs for both modes, including verdict categories, per-leg fill detail, and risk warnings (thin_legs, forced_directional_risk). It is sufficiently complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: clarifies 'side' defaults and auto-detection for basket mode, explains 'size_usd' interpretation (spend vs proceeds for single-market; settlement notional for basket), and describes return fields in detail. This goes well beyond what the schema provides.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', specifying two distinct modes (single-market and basket). It directly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by context and usage.

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 to use this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. Also warns about risks of partial basket fills converting arb into unhedged positions, providing clear when-to-use and when-not-to conditions.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds critical behavioral context: compatibility_warning conditions, temporal alignment checks, and skipped cross-type/subtype 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 detailed and well-structured with bold headings for modes and safety fields. Every sentence adds value, though slightly verbose. Front-loads the core purpose and modes effectively.

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

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

No output schema exists, but the description thoroughly explains response fields: raw probabilities, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. Covers all essential aspects for proper interpretation.

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 property descriptions by explaining the topic shortcut list, override behavior, and usage examples. It enriches understanding of custom pairings.

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 precisely states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings (e.g., polymarket_arbitrage) by focusing on cross-venue differences. Two modes and response structure clarify its purpose.

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

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

Explicitly explains when to use (when bet shapes are equivalent) and when not (compatibility_warning scenarios). Warns that most pre-mapped topics return warnings, setting proper expectations. Provides clear context for both topic and explicit modes.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. Description adds context on scoping (anonymous IP, key hash, account ID) and listing behavior when key omitted, adding value beyond annotations.

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

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

Three sentences, front-loaded with core purpose, no superfluous words. Every sentence provides essential 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?

For a simple retrieval tool with no output schema, the description covers behavior, scope, and lifecycle pairing completely. No gaps given the complexity.

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

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

Schema has 100% coverage with one optional key parameter. Description adds meaning by explaining omission lists all keys and gives examples of key values, clarifying usage beyond schema.

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

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

The description clearly states the tool retrieves a saved value by key or lists all keys, using specific verbs (retrieve, list) and distinguishes it from siblings remember and forget.

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

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

Explicitly describes when to use (look up stored context, avoid re-deriving) and provides example use cases (target ticker, address, notes). Mentions pairing with remember/forget for lifecycle management.

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 annotation readOnlyHint: true indicates the tool should not modify state, but the description states setting mark_read:true flags returned events as read, which is a state modification. This contradiction undermines transparency. Despite the description disclosing the side effect, the contradiction with annotations leads to a low score.

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

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

The description is efficient with 4-5 sentences, front-loading the main purpose. It is clear but could be slightly more concise. No unnecessary fluff.

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

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

For a tool with no output schema, the description thoroughly explains return fields (source, citation_uri, raw payload), acceptable usage (polling), and an alternative access method. It covers all five optional parameters adequately.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the mark_read side effect, providing an example for type filtering, and detailing return fields not in the schema (source, citation_uri, raw payload). This extra context justifies a score of 4.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts with specific fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription listing.

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

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

The description provides guidance on filtering by type and since timestamp, using mark_read for read tracking, and notes polling is acceptable. It also mentions an alternative HTTP endpoint for scripts, but does not explicitly exclude when to use this tool versus sibling tools like list_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?

Describes data sources (SEC, GDELT, GNews, USPTO), fallback logic, return structure (changes grouped by source), and soft-fail behavior. Adds significant 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 examples first then details. Slightly long but every sentence is valuable.

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

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

Complete coverage of tool behavior, sources, parameters, return format, and alternatives. No gaps despite no 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 description adds meaning: type constraint, relative shorthand for since (with examples), value formats (ticker/CIK), and recommended monitoring interval.

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

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

The description clearly states the tool's purpose as a change feed for a company within a time window, with example queries. It distinguishes from sibling tool 'entity_profile' for static profiles.

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

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

Provides explicit usage examples and directs to entity_profile for static profiles. Could be more specific about when not to use, but the alternative is clearly stated.

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 a mutating, idempotent, non-destructive operation. The description adds valuable context: key-value scoping by identifier, 24-hour retention for anonymous sessions, and pairing with recall/forget. 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 three sentences, front-loaded with purpose and use cases, then storage details. No redundant or vague language; every sentence contributes meaning.

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

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

Given the low complexity (2 parameters, no output schema), the description covers all necessary context: action, usage guidance, storage behavior, and tool relationships. Annotations fill remaining gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minor value by suggesting key naming conventions (e.g., 'subject_property') and clarifying value type as 'any text', but does not fundamentally extend 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 ('Save data') and the resource ('data the agent will need to reuse later'), with specific examples like resolved tickers or user preferences. It distinguishes from sibling tools 'recall' and 'forget' by naming them as counterparts.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples. It mentions pairing with 'recall' and 'forget', and notes persistence differences, but does not explicitly exclude alternative use cases.

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

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

Adds substantial behavioral context beyond annotations: describes graceful degradation of LEI/FIGI enrichment when GLEIF/OpenFIGI is unavailable, explicit unresolved identifier disclosure, source labeling, and internal cascading lookups that replace multiple manual steps. This is precisely the kind of nuance that helps an agent predict outcomes.

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

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

The description is longer than ideal but extremely well-structured: begins with user-phrase examples, then a 'use FIRST' directive, then a clearly separated SUPPORTED TYPES section. Every sentence carries purpose; the density is justified by the range of entity types and sources, though it could be trimmed slightly.

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

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

For a tool with two entity types, multiple identifier sources, and fallback behavior, and with no output schema, the description covers the key aspects: how identifiers are labelled, unresolved identifiers are explicitly listed, and degradation behavior. It gives an agent enough to invoke correctly and interpret results with minimal surprises.

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 both parameters, so baseline is 3. The description goes further by enriching the 'type' parameter with per-type behavior (company vs. drug) and providing concrete examples for 'value' (AAPL, 0000320193, ozempic). It also explains that enrichment may fail gracefully, but this is more output-oriented than strictly parameter semantics.

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

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

The description states a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'), and explicitly notes that it produces IDs other tools require as input, distinguishing it from siblings like entity_profile or compare_entities. Examples like 'What's the ticker for…' immediately clarify the tool's role.

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 strong contextual guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies supported entity types and input formats. However, it does not explicitly name alternative tools or state when not to use it, leaving some ambiguity for edge cases where another sibling might be more appropriate.

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 that it internally calls ai_visibility_check, ranks by score, and surfaces most/least recognized. 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?

Three sentences, front-loaded purpose, zero waste. Each sentence adds distinct value.

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

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

No output schema, but description explains return format (ranked list with score, confidence, signal density). Process of probing each entity with ai_visibility_check is described. 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?

100% schema coverage gives baseline 3. Description adds extra: first entity treated as subject, optional models with _apiKey dependency. Adds 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?

Verb 'compare' + resource 'AI visibility across multiple entities' + outcome 'ranked list with score, confidence, signal density'. Distinguishes from single-entity sibling ai_visibility_check.

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 use case: competitive AI-marketing audits. Implies when to use but does not explicitly state when not to or mention alternatives like compare_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?

Description adds behavioral details beyond annotations: fans out across two sources, partial failures degrade gracefully, bundlephobia may take 5-30s, and sources_failed is listed if timeout. No contradiction with annotations.

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

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

Description is front-loaded with purpose and is structured logically, but is somewhat verbose (multiple sentences). Still, every sentence adds value, so 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 fully explains return format (summary block fields, per-advisory detail, links, alternative versions) and error handling (partial failures). Given tool complexity with 2 params and no output schema, it is 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 covers 100% of parameters, so baseline is 3. Description adds value by clarifying that scoped packages (e.g., "@types/node") are accepted for 'package' and that 'version' defaults to latest when omitted.

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 a specific verb and resource: 'Composite check for evaluating whether to add an npm package'. It distinguishes itself from siblings by specifying NPM-only and mentioning alternatives like deps.dev:version for other ecosystems.

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 agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and identifies limitations: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds specific technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation, and return of character offsets. 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 five sentences that front-load the purpose and follow with necessary details. It is concise without redundancy, though slightly more efficient phrasing could be used.

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

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

Despite no output schema, the description fully explains the return format (top-N passages with character offsets and similarity scores), the embedding model, window size, and truncation behavior. It is complete for understanding the tool's behavior.

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

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

Schema description coverage is 100% (all three parameters have descriptions). The description does not add new information beyond what the schema provides for the parameters (e.g., the 200K cap is in both). Baseline of 3 is appropriate as the schema carries the burden.

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 ('Semantic search INSIDE a fetched record') and the resource ('a fetched record'). It distinguishes itself from siblings by explaining it is for large records that cannot fit in the prompt and pairs with ask_pipeworx_grounded.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document' using ask_pipeworx_grounded.

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 (idempotentHint=true, etc.), the description adds behavioral details: OAuth requirement, SMS cap (10/day), phone verification prerequisite, webhook signing secret returned once, and auto-disabling after 10 consecutive failures. No contradiction with annotations is present.

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

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

The description is well-structured, starting with the main purpose, then requirements, type examples, and delivery details. It is efficient and front-loaded, though the webhook paragraph could be slightly condensed.

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 only minimally states 'Returns the new subscription id.' Lacks details on the full response format, subscription lifecycle, and idempotency behavior (especially relevant given idempotentHint=true). Hits the essential points but leaves some 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?

Despite 100% schema coverage, the description significantly enhances parameter understanding with real-world examples, nested object structures, and constraints (e.g., SMS cap, phone verification, webhook HMAC). This goes well beyond the schema's isolated 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 verb ('Create'), the resource ('proactive monitoring subscription to a live-data event stream'), and explicitly mentions return of the new subscription ID. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description specifies that a Pipeworx OAuth account is required and that anonymous/BYO users cannot persist subscriptions, providing clear when-to-use and when-not-to-use guidance. It does not explicitly name alternative tools but gives sufficient context to distinguish.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds that the tool returns example questions with tool+argument shapes, and that it can be called with or without a topic. No behavioral surprises.

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

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

The description is dense but well-organized: starts with aliases, then purpose, then output detail, then usage instructions. Every sentence adds value, though it could be slightly shorter.

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 discovery tool with one optional parameter and no output schema, the description covers use cases, parameter options, and output category. It lacks an explicit example of the return format, but the context is sufficient.

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

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

Schema coverage is 100% and already describes the topic parameter well. The description adds minimal extra context (e.g., 'e.g. finance') and restates the schema, so it provides limited additional meaning.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions and is the onboarding entry point. It distinguishes from siblings by explicitly recommending it 'FIRST' and naming alternatives like ask_pipeworx.

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: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to pass a topic vs call with no arguments.

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 key behavioral details beyond annotations: ownership enforcement, row deactivation vs deletion, and impact on historical alerts. No contradiction with annotations; aligns with idempotentHint and destructiveHint.

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

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

Two concise sentences with no wasted words. Front-loads the main action and provides all necessary context efficiently.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, behavioral impact (deactivation), and side effects (historical events preserved), fully addressing agent needs.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The description adds no additional parameter-level detail beyond the schema, meeting the baseline expectation.

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

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

The description clearly states the action ('Cancel a subscription by id'), identifies the resource (subscription), and implicitly distinguishes from siblings like 'subscribe' and 'list_subscriptions' through the 'cancel' verb.

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?

Describes ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. Also explains the effect on historical events, though lacks explicit alternatives or when-not-to-use conditions.

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

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

Beyond annotations (readOnly/openWorld/idempotent), the description discloses crucial behavioral details: could_not_verify means the check did not happen and must not be treated as evidence; unsupported means no source coverage. Also exposes the internal pipeline and return structure (verdict, value, citation, reasoning).

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

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

Description is long but every sentence provides valuable information: trigger phrases, routing, verdict types, error semantics, and efficiency claim. Structure is logical and front-loaded with the core purpose. Slightly overlong, but appropriate for 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 there is no output schema, the description fully explains return values: verdict enum with six possible values, actual value with citation, and reasoning. Also covers error conditions (verification_error) and distinguishes edge cases. All necessary operational context is present.

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

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

Input schema already documents both parameters well (claim with examples, tolerance_pct with range and default). Description adds meaningful nuance: tolerance_pct overrides implied wording and is capped at 5 by default, plus guidance for hallucination detection. 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?

Description clearly identifies the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that.' It distinguishes itself from sibling research tools by focusing on true/false verdicts and providing structured verdict categories.

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

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

States explicitly to use when the agent needs to check factual correctness of a user statement. Also explains routing logic: financial claims via SEC EDGAR/XBRL, any other claims via grounded pipeline. This gives clear, actionable guidance and differentiates from alternatives.

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