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 readOnly/openWorld/idempotent/non-destructive behavior, and the description adds useful behavioral context: it fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is described as one fast call. It also implies a limitation by recommending ask_pipeworx_grounded for verbatim evidence and confidence.

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 average, but it is front-loaded with the 'PREFER OVER WEB SEARCH' directive and each section serves a routing purpose: scope, triggers, examples, and alternatives. It is slightly wordy and repetitive, so it does not earn a 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?

For a broad default router with no output schema, the description covers when to use it, what it returns, how it handles live news, and which sibling to escalate to. Nothing an agent needs to decide whether to call it, or what question to pass, 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% and all six parameters are aliases of 'question', so the schema fully documents the parameter surface. The description provides example questions but does not add semantic meaning beyond what the schema already supplies; 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 identifies a broad routing/search purpose: it 'routes the question to the right one of 5,743 tools' and returns structured answers with citations. It also distinguishes itself from web search and from sibling tools like ask_pipeworx_grounded and deep_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?

The description gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and says to prefer this tool over web search. It also states exactly when to step up: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for 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 annotations, the description discloses that candidate routing improvements may be enabled live, that no candidate is currently active, and that it is a full working router with no fallback. This is exactly the kind of behavioral context an agent needs to trust the 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 compact, front-loaded with the tool's beta identity, and every sentence adds necessary context: identity, current state, usage guidance, and reassurance against fallback concerns. There is no 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 universal router with no output schema, the description covers all critical aspects: what it routes to, how it relates to ask_pipeworx, current experimental status, expected use, and the absence of a fallback. Nothing needed for correct invocation 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 description coverage is 100%, so the schema fully documents all parameter aliases. The description only says 'same arguments' without adding further parameter semantics, which matches the baseline expectation when 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes it from the stable router by its experimental status, leaving no ambiguity about what the tool does.

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

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

It gives an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison to the stable router. This tells the agent when to choose this tool over the obvious sibling alternative.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description goes well beyond this by disclosing the exact output contract on success and failure, enumerating specific refusal reasons, and explaining the constraint that answers come only from the tool result. This is substantive behavioral information an agent would not otherwise know.

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?

Despite its length, every sentence adds operational value: the core behavior is front-loaded, the return contract is specified precisely, usage scenarios are named, and the cost comparison is included. The refusal-reason enumeration is dense but directly actionable for an agent deciding whether to retry or report failure.

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 fully specifies both success and failure return shapes, key fields, refusal reasons, and the extra LLM call cost. It also clarifies the relationship to the sibling ask_pipeworx tool. No critical calling information appears to be 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?

Input schema coverage is 100%, with all six parameters documented as aliases for the free-text question. The description does not add parameter-specific detail, but the schema already handles that burden fully. The baseline of 3 applies because the description adds no extra meaning beyond the schema's clear alias documentation.

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 precise purpose: a hallucination-resistant answer mode that extracts answers only from tool results. It explicitly differentiates itself from ask_pipeworx by describing the extraction and refusal behavior, making the tool's unique function unmistakable.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on.' It also names the alternative (ask_pipeworx) and gives a clear exclusion criterion: 'prefer ask_pipeworx for casual lookups.' The cost tradeoff is also stated, which helps an agent decide correctly.

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?

Even with readOnlyHint=true, idempotentHint=true, and destructiveHint=false already in annotations, the description adds substantial behavioral context: account/plan requirements, parallel facet decomposition, findings packet format with verbatim evidence and citations, gaps[] behavior, contradictions[], excerpting semantics, hop fields, and expected latency. It fully discloses how the tool behaves beyond what annotations state.

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

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

The description is long but every sentence earns its place: prerequisites first, then core function, then sibling differentiation, then depth semantics, then return behavior, then timing. The structure is dense but logically ordered and front-loaded with the account gate that determines whether the tool can be used at all.

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

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

For a complex tool with no output schema, the description covers all essential operational knowledge: when it is appropriate, what it returns, how citations work, what gaps[] means, what depth levels do, and how long calls take. An agent has enough information to select, invoke, and interpret results 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?

While the schema already covers 100% of parameters, the description enriches both meanings substantially: it explains what 'question' should look like (broad/multi-part is fine) and details each depth value's behavior beyond the schema enum text (quick=3 facets, standard gap recovery, thorough lead-chasing and contradiction scanning). This goes well beyond the baseline for high schema coverage.

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

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

The description clearly states the verb and resource: grounded multi-source research over Pipeworx's 1500 structured data sources, decomposing questions and routing to 5,743 tools. It explicitly differentiates itself from open-web search and from ask_pipeworx, which prevents confusion with the primary sibling. This is specific and actionable.

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

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

The description gives explicit when-to-use guidance for broad/multi-part structured-data questions and explicit when-not-to-use guidance for single lookups and breaking/current-news topics. It names the alternative tools (ask_pipeworx) and even covers the auth-tier case (use ask_pipeworx if not signed in). Nothing is left to inference.

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

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

Annotations already 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?

Beyond the readOnly/idempotent annotations, the description discloses per-section behavior: patents soft-fail due to a USPTO sunset, an empty fda_products section is expected for non-biologic companies, empty sections are real no-data rather than bugs, and sources_used/sources_failed report provenance. This is exactly the kind of failure-mode and edge-case transparency agents need.

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 the tool is genuinely multi-source and the length is mostly earned through concrete return-field and failure-mode details. It is front-loaded with example queries and the core purpose before enumerating sources, though the dense semicolon-list style could be improved with short section breaks.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: it enumerates every returned section (filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI) and adds source-failure semantics. It also covers the important resolving behavior for private companies, so an agent has enough context to invoke and interpret the call 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?

The input schema already covers the two parameters and their allowed value shapes at 100% coverage, so only a small premium is earned here. The description adds useful context by noting case examples, that type is interchangeable, and that name inputs resolve via SEC EDGAR with resolved_from/resolved_to behavior, which goes slightly beyond the schema.

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

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

The description opens with concrete user phrasings and then states a precise verb + object: "full cross-source profile of a US public company in ONE parallel call." It names the main alternatives it replaces (chained single-pack SEC/XBRL/news lookups) and clarifies it is for holistic profiles, distinguishing it from the many research 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?

It explicitly instructs to "ALWAYS PREFER" this tool over chaining single-pack lookups when the user wants a holistic view, and it notes the exception behavior for private companies (resolved:false with notes) so the agent knows when the tool has done its job. This is actionable when/when-not guidance rather than a vague invitation to use it.

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

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

Annotations already 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?

This is unusually transparent: it discloses safety fields, the meaning of compatibility codes, when pairing_unverified is set, how unclassified legs are handled, temporal alignment pitfalls, fees not being modeled, and skipped comparison counters. All of this goes far beyond the readOnly/openWorld/idempotent annotations and gives an agent a clear model of the tool's limitations.

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 it is densely packed with non-redundant operational detail and logically organized into mode, response, safety fields, and limitations. Every section earns its place, though a tighter version could condense the early '2-25pp' explanatory clause without losing essential guidance.

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, the absence of an output schema, and the need to interpret safety fields and caveats, the description is remarkably complete. It covers response contents, warning codes, skipped comparisons, temporal alignment semantics, and fee modeling limitations, leaving an agent with enough information to call the tool correctly 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?

Although the schema already describes the three parameters, the description adds substantial meaning: topic maps to named shortcuts, explicit ticker/slug override the mapped side, and both modes use the same token-overlap matcher with the same disclosures. This helps an agent correctly compose custom pairings and understand the relationship between the 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 opens with a specific verb and resource: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It further clarifies the core signal and the circumstances under which it is meaningful, making the tool's purpose unmistakable and distinct from sibling analytics tools.

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

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

The description explicitly lays out two usage modes ('topic' shortcuts vs explicit event identifiers) and how they interact, including the fact that both run the same matcher. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped does not mean tradeable, though it does not explicitly name sibling tools as 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 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?

The annotations already mark the call as read-only, open-world, and idempotent, and the description adds substantial behavioral detail beyond those flags: graceful degradation if GLEIF/OpenFIGI are unavailable, explicit `unresolved` output rather than silent omission, candidate-based behavior for ambiguous instruments, and internal cascading across multiple lookup endpoints. It accurately discloses edge-case behavior an agent would otherwise not infer.

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 and dense, but the length is justified by the complexity of multi-source identifier resolution. It is front-loaded with the core purpose and usage trigger, then uses clear section labels (SUPPORTED TYPES, LEI/FIGI enrichment, cascading behavior). Some parenthetical density could be tightened, but every substantive block 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?

Despite having no output schema, the description explains what callers will receive: source-labelled identifiers, `figi_candidates` for ambiguous matches, `unresolved` entries for missing identifiers, and the RxCUI citation format. It also covers supported input formats, resolution strategy, and failure modes, so an agent has the context needed to invoke and interpret 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?

Even with 100% schema coverage, the description materially enriches parameter semantics: it clarifies that `value` should be the ENTITY NAME ONLY, gives examples of correct vs. incorrect inputs for bonds, and explains how ISINs map to legal entities. The `type` parameter benefits from the detailed company/drug behavior descriptions, going well beyond the enum labels in the schema.

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

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

The description states a precise purpose: resolving a user-spoken NAME into canonical identifiers (CIK, ticker, LEI, RxCUI, FIGI) that other tools require. The opening example queries and explicit "Use FIRST whenever you have a name but need an ID" make the tool's role unmistakable and distinguish it from siblings like entity_profile, which would provide broader profile data rather than ID 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?

The description provides clear when-to-use guidance: "Use FIRST whenever you have a name but need an ID," supported by representative user queries and the SUPPORTED TYPES breakdown. It stops short of naming alternative tools to use when this tool is not appropriate, but the trigger conditions and coverage limits are explicit enough for an agent to select it correctly.

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.