Confluence

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

Annotations already provide readOnly, idempotent, openWorld hints. The description adds value by explaining the probing behavior, scoring mechanism, return structure (per-model + combined view), and API key handling (BYO key for Anthropic, payment details). 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 three sentences: action and resource, model details and key usage, return format, and use cases. Every sentence adds value, no fluff. Front-loaded with the main purpose.

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

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

Given 4 parameters, high schema coverage, no output schema, the description adequately explains the return structure (per-model fields + combined view), model options, and use cases. No missing information for a tool of this 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 descriptions already define parameters. The tool description adds context: default model is free, _apiKey is optional and passed through, context helps disambiguate. This goes beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the verb 'Probe' and the resource 'LLMs for what they know about a business/brand/product/topic' with scoring. It provides specific output details (score 0-100, per-model fields, combined view) and distinguishes from sibling tools like ask_pipeworx (specific entity) and compare_entities (comparison).

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

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

The description gives explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and guidance on model selection (default Workers AI, optional Anthropic with key). It does not explicitly state when not to use or compare to alternatives, but the sibling tool names imply alternatives for specific tasks.

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

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

Annotations already cover readOnly, idempotent, etc. The description adds value by explaining the routing mechanism (to one of 3,770 tools) and that it returns structured answers with stable citation URIs. It does not mention rate limits or failure modes, but the annotations sufficiently cover safety.

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 slightly long but front-loaded with the key preference statement. Each sentence provides necessary information. A more concise version could exist, but it is well-structured and earns its length.

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

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

Given the complexity of the tool and no output schema, the description adequately explains what the tool does and provides rich examples. It lacks details on error handling or ambiguous queries, but overall it is complete enough for an agent to select 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 description coverage is 100%, so baseline is 3. The description adds no new semantic meaning beyond what the schema provides (the aliases are already listed). It does contextualize the parameter with examples, but that is not adding semantic 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: answering factual questions using authoritative structured data from thousands of sources. It specifies verb+resource ('routes the question to the right one of 3,770 tools') and distinguishes from web search, which is a key differentiating factor. The examples solidify the purpose.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides a comprehensive list of query types and domains. However, it does not differentiate from sibling tools like 'pipeworx_grounded' or 'deep_research', missing an opportunity to guide when to use this tool versus alternatives within the tool set.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral details like hallucination resistance, extra LLM call cost, and explicit refusal codes, which provide context beyond annotations.

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

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

The description is well-structured with front-loaded purpose, but slightly verbose. Every sentence adds value, though it could be more concise without losing clarity.

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

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

Given no output schema, the description comprehensively explains the return structure (answer, evidence, confidence, etc.) and possible refusal reasons. Covers all necessary context for an agent to use the tool correctly in high-stakes scenarios.

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 multiple aliases for the question parameter. The description mentions 'accepts query, q, prompt, text, input as aliases' but this is already in the schema. No additional meaning beyond the schema.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains its process of routing, argument filling, and extracting answers only from tool results. It distinguishes from the sibling 'ask_pipeworx' by noting the extra LLM call and preference for casual lookups.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' Provides both when-to-use and when-not-to-use with alternative mentioned.

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

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

The description extensively discloses behavioral traits beyond annotations: resolver contract (market_match_confidence, alternatives, suggestions), parent event extraction, news fallback details, safety short-circuits for low-confidence and closed markets, wide-spread tradeability notes, and resolution-rule risk. Annotations already indicate readOnly and idempotent, and the description adds significant context 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 well-structured with sections, examples, and bullet points. It is front-loaded with the primary purpose and provides detailed information. However, it is quite lengthy, which may reduce conciseness, but the structure helps maintain clarity.

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

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

Given the tool's complexity (multiple fan-out paths, response shapes, safety checks, and edge cases), the description is remarkably complete. It explains return values (result.market, result.analysis, result.evidence, etc.) in detail, even though there is no output schema. All important behaviors and conditions are covered.

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

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

Schema coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description reinforces parameter usage but does not add substantial new meaning beyond the schema. For example, it explains market input types (slug, URL, question) which are already in the schema description.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data aggregation for a single market input.

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

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

The description provides explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes examples of fan-outs for different bet types. However, it does not explicitly exclude use cases or mention when to prefer a sibling tool over this one.

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 (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral details: it pulls live SEC data for companies and FAERS data for drugs, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. It also states that it makes one parallel call, which informs the agent about its performance characteristics.

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

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

The description is information-dense but front-loaded with example queries that quickly convey intent. While it is somewhat long, every sentence adds unique value (e.g., data sources, sorting behavior, citation format). Minor improvements could be made with bullet points or clearer separation between company and drug cases, but overall it is well-structured.

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

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

Given the lack of an output schema, the description thoroughly explains what the tool returns: paired data with citation URIs per entity, sorted by primary metric. It covers both entity types completely, including details like handling off-calendar fiscal years. An agent has all necessary information to invoke the tool and interpret its response 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 schema covers 100% of parameters with descriptions, but the tool description adds significant value by providing concrete examples (e.g., ['AAPL','MSFT'] for companies, ['ozempic','mounjaro'] for drugs) and explaining how each type influences the data pulled. This helps the agent formulate correct inputs beyond the schema's enum and array definitions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It specifies the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and the output format (paired data + citations). It distinguishes itself from sequential single-pack lookups, which are likely performed by sibling tools like 'entity_profile'.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use this tool instead of alternatives. It also includes example queries like 'compare X and Y' and estimates that it replaces 8-15 sequential lookups, reinforcing its efficiency for comparisons.

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 that the tool returns 'page ID and URL,' adding behavioral info beyond annotations. Annotations indicate it's not read-only, not destructive, and idempotent. No contradictions. The description could mention idempotency implications but suffices.

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 efficiently cover purpose, input options, and output. No redundant or vague language. Every sentence contributes directly to agent understanding.

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

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

With 5 parameters and an output schema, the description adequately covers inputs and outputs. It could mention error handling or XHTML body format, but schema already addresses body format. Sufficient for a straightforward creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by interpreting parameters: it clarifies that spaceKey (e.g., 'ENG') can be used as spaceId, and mentions parentId is for nesting. Examples in schema supplement this.

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

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

The description clearly states the tool's purpose: 'Create a new Confluence page with title and content.' The verb 'create' and resource 'Confluence page' are specific. It distinguishes itself from sibling tools like confluence_get_page (get) and confluence_list_pages (list) 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 provides practical guidance: 'Specify parent page ID or space key (e.g., "ENG").' This tells the agent what parameters to use and gives an example. While it doesn't explicitly exclude alternatives, the context is clear for creating a page.

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, and idempotentHint. The description adds value by listing the return fields (title, body, status, version, space info), but does not disclose any additional behavioral traits like authentication or rate limits.

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

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

The description is a single sentence of 17 words, front-loading the purpose and listing return fields. Every word adds value; there is no redundancy or extra text.

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

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

Given the simple tool with full schema coverage, helpful annotations, and an existing output schema, the description is complete. It covers the core functionality and return types 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% and parameter descriptions in the schema are complete. The description adds no additional meaning beyond stating 'by ID' and mentioning return fields, which is already covered by 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 verb 'Get' and the resource 'full content of a Confluence page', listing specific return fields (title, body, status, version, space). It distinguishes itself from siblings like 'confluence_list_pages' and 'confluence_search' by targeting retrieval by ID.

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

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

The description implies the tool is for retrieving a known page by ID, which is clear from the required parameter. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance, even though siblings exist.

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 and idempotentHint. The description adds that it returns page ID, title, status, and version, providing useful context beyond annotations without contradicting them.

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

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

Two concise sentences that front-load the core purpose and quickly mention return fields and usage hint. Every sentence adds value with 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?

With an output schema present and good annotations, the description is adequate. It covers the primary purpose, required input, and return fields, leaving little ambiguity for the 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 the schema fully documents parameters. The description offers example values for space key but does not add significant meaning beyond the schema.

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

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

Description clearly states it lists pages in a Confluence space, specifying the resource (pages) and action (list). It distinguishes from siblings like 'confluence_search' or 'confluence_get_page' by focusing on listing within a space.

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 tells users to specify a space key and provides examples, implying when to use. However, it does not explicitly state when not to use this tool versus alternatives like searching across spaces.

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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already cover safety and side effects. The description adds that it returns specific fields but does not clarify pagination behavior or that 'all' spaces may be limited by the 'limit' parameter. The description adds marginal value over annotations.

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

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

Two concise sentences with no fluff. The first sentence states the action and return values; the second gives a usage hint. Information is front-loaded and efficient.

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

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

The description is largely complete for this simple tool with 2 optional parameters, full schema coverage, and an output schema. However, it lacks mention of pagination or that the 'limit' parameter caps the result size, which is a minor gap.

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 having descriptions. The tool description does not add additional meaning or context for the parameters beyond what the schema already provides. It mentions output fields, not parameter details.

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', the resource 'spaces', and the return values (ID, key, name, type, status). It distinguishes from sibling tools like 'confluence_list_pages' by focusing on spaces.

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 an implied usage ('Use to discover documentation areas') but does not explicitly state when to use this tool versus alternatives like 'confluence_search' or 'confluence_list_pages'. No exclusions or when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is clear. Description adds value by specifying output fields (ID, title, space, content excerpt). No contradictions.

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

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

Two sentences with no fluff. Action verb and resource are front-loaded. 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?

With output schema present and comprehensive input schema, the description is nearly complete. However, missing details on result ordering and pagination behavior (beyond limit parameter) prevent a 5.

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

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

Input schema has 100% description coverage with examples for cql and limit. Description adds no new parameter meaning beyond what the schema provides; 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?

Description clearly states the tool searches Confluence pages by keyword or CQL query, and specifies returned fields (ID, title, space, content excerpt). This distinctly separates it from sibling tools like confluence_get_page (single page) and confluence_list_pages (no search).

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

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

Description mentions search by keyword or CQL but provides no guidance on when to use which, nor exclusions vs alternatives. It is adequate but lacks explicit usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it explains the parallel decomposition process, structured output (verbatim evidence, confidence, source, gaps), and the guarantee that facts are never invented ('explicit gaps[]'). No contradictions.

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

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

The description is front-loaded with the main purpose and contains no wasted sentences. However, it is somewhat lengthy (10+ sentences) and could potentially be tightened without losing meaning. Still, every sentence contributes to understanding.

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 does an excellent job of explaining what the return value contains: a structured findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[]. It also explains the process and expected latency (15-60s), making the tool's behavior fully predictable.

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. The description reinforces the meaning of the depth parameter (quick=3, standard=5, thorough=8) and adds context about paid plans for thorough. It does not introduce entirely new semantic information beyond the schema, but it does enrich understanding.

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

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

The description clearly states the tool's core function: 'Grounded multi-source research in ONE call.' It explains how it decomposes questions, routes to 3,770 tools in parallel, and extracts structured answers. It distinguishes itself from sibling tools like ask_pipeworx, leaving no ambiguity about its unique role.

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

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

The description provides explicit guidance on when to use this tool: for broad or multi-part questions ('compare X and Y', 'regulatory + financial + market picture'). It explicitly contrasts with ask_pipeworx for single lookups. It also notes prerequisites (Pipeworx account) and pricing restrictions for the 'thorough' depth level.

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 and idempotentHint. The description adds that results are 'ready to call directly, no second schema lookup needed,' providing behavioral context beyond the annotations. No contradictions.

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

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

The description is 4-5 sentences, with each sentence serving a purpose: stating the verb, listing domains, explaining output, and giving usage guidance. It is front-loaded and efficient with no unnecessary words.

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

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

Although there is no output schema, the description explains the return format (top-N tools with names, descriptions, schemas, and examples). It covers the return value and usage context. Given the tool's simplicity, it is sufficiently complete.

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

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

Schema coverage is 100% with full descriptions for each parameter. The description includes example queries like 'analyze housing market trends' but does not add meaning beyond the schema's aliases and examples. Minimal added value.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific domain examples (SEC filings, financials, etc.) and explains that it returns top-N relevant tools with schemas, distinguishing it from sibling tools like direct data query tools.

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

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

The description explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear context but does not explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich context: it fans out across multiple sources, mentions a soft-fail for patents API, and details the return structure including fields like cik, filings, fundamentals, etc.

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

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

The description is front-loaded with example queries, making purpose immediately clear. While slightly lengthy, every sentence is informative with no fluff. Could be slightly more concise, but structure is effective.

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

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

Despite no output schema, the description enumerates all return fields (cik, name, filings, fundamentals, patents, news, LEI) with explanations. It also addresses the patents API sunset and fallback. Minor omission: no mention of pagination or limits, but sufficient for a profile 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 detailed descriptions for both parameters (type enum, value ticker/CIK). The description repeats this information without adding new meanings beyond examples. Per guidelines, 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 provides a 'full cross-source profile of a US public company in ONE parallel call', listing specific data sources and outputs. It distinguishes itself from siblings like 'resolve_entity' by noting that names are not supported here.

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view' and warns that names are not supported, directing users to use 'resolve_entity' first. Provides concrete examples of when to use.

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

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

Annotations already indicate destructiveHint=true, so the description's 'Delete' and 'clear sensitive data' align but add limited new behavioral insight beyond confirming the destructive nature.

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

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

The description is two sentences, front-loaded with the purpose, and contains no extraneous information.

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

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

Given the tool's simplicity (one required parameter, no output schema) and annotations, the description sufficiently covers usage, pairing suggestions, and purpose. No gaps identified.

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

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

Schema coverage is 100%, and the description does not elaborate on the 'key' parameter beyond what the schema provides. Baseline score applies.

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

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

The description clearly states 'Delete a previously stored memory by key,' providing a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by being the deletion counterpart.

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

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

The description explicitly says 'Use when context is stale, the task is done, or you want to clear sensitive data' and directs pairing with 'remember' and 'recall,' offering clear when-to-use and alternative context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the tool is clearly non-destructive and idempotent. The description adds process details ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'), which provides behavioral context beyond the annotations.

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

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

The description is moderately concise, with three sentences covering purpose, process, and use cases. It is front-loaded with the core action. However, it could be slightly tightened by removing redundant phrases like 'production-ready' or 'cleanly'.

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

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

Given the tool has only 2 parameters, no output schema, and rich annotations, the description covers the key aspects: what it does, how it works, and when to use it. It lacks details about error handling or limitations, but for this tool's simplicity, it 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 description coverage is 100%, so the schema already documents both parameters clearly. The description mentions 'Fetches the page, extracts title/description/key links' which implies the URL is used for fetching, and max_links is implied to limit links, but adds no new semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for any URL. It specifies the output format (standard llms.txt markdown) and explicitly lists use cases, distinguishing it from sibling tools like 'scan_competitor_ai_presence' and '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?

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), giving good context for when to use the tool. It does not mention when not to use it or compare directly to alternatives, but the use cases are clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it returns specific fields (id, type, params, etc.), lists only active subscriptions by default, and mentions the include_inactive parameter. No contradictions with annotations.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. No unnecessary words. Information is front-loaded and efficient.

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

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

Given no output schema, the description explicitly lists the return fields (id, type, params, created_at, last_fired_at, fire_count). It covers default behavior and parameter usage. With sibling tools, the description fully enables correct invocation without 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 one parameter ('include_inactive') well described. The description adds context by stating that it lists 'active' subscriptions by default, reinforcing the parameter's purpose. However, it doesn't add significant new meaning beyond the schema.

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

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

The description clearly states the action ('List') and the resource ('the caller's active subscriptions'), and specifies the scope ('caller's'). It distinguishes itself from sibling tools like subscribe and unsubscribe by being a read-only list. No ambiguity.

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

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

The description provides explicit guidance on when to use the tool: 'review what you're monitoring before adding more' and 'find an id to cancel'. While it doesn't explicitly state when not to use it, the context is clear and helpful. It effectively differentiates from siblings.

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

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

Annotations are all false, and the description adds valuable context: free, not counted against quota, daily rate limit of 5, team reviews digests, signal affects roadmap. 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 structured well, but slightly verbose. Every sentence adds value, though it could be trimmed while retaining key details. Still, it's effective and not wasteful.

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

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

Given the tool's simplicity (no output schema, few parameters), the description fully covers all necessary context: what to include, what to avoid, constraints (rate limit, quota), and intended use cases. No gaps.

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

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

Schema coverage is 100% with clear descriptions for each parameter (type enum, context object fields, message). The description adds usage nuance (e.g., be specific, 1-2 sentences) but does not provide new semantic 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 uses specific verbs like 'tell' and 'send feedback' and explicitly lists use cases: bug, feature/data_gap, praise. It clearly distinguishes itself from sibling tools by being the only feedback channel.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and when-not-to-use (don't paste user prompt), plus rate limits and quota details, leaving no ambiguity.

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, idempotent, non-destructive. Description adds caching behavior (5min-1h), data source (CF analytics-engine), and no PII assurance, providing valuable context beyond annotations.

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

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

Two sentences plus a clear bullet list of use cases. Every sentence is informative and well-structured, with no wasted words.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers return values, use cases, caching, and data sourcing. Could mention rate limits or result size, but not essential.

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 well-described enum parameter. The tool description adds no additional parameter context, so baseline 3 applies.

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

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

Description clearly states the tool returns top tools, packs, and call volume over recent windows, distinguishing it from siblings like ask_pipeworx or discover_tools by focusing on aggregated agent 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?

Three explicit use cases are provided, covering discovery, confirmation, and alignment. While no alternatives or exclusions are mentioned, the guidance is clear and actionable.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it explains the two search modes, semantic anchor (Jaccard similarity), partition filter, how fill check uses CLOB depth, and what the response contains. No contradictions with annotations.

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

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

The description is well-structured with sections for each mode, filters, and fill check. It front-loads the critical requirement (REQUIRES one of event or topic). It is fairly long but every sentence adds necessary detail. Minor room for trimming redundant phrases like 'do not trade it' which is implied by the fill check logic.

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 (two modes, multiple checks, and response structure), the description covers all essential aspects. It explains the response fields, the fill check, and the conditions under which the tool returns null signals. No output schema is provided, but the description compensates with detailed response format.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by explaining the difference between the two parameters in context, providing examples of values, and describing the behavior of each mode. However, the schema descriptions already give good hints.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It explicitly distinguishes two modes (event and topic) and provides concrete examples. This differentiates it from sibling tools like polymarket_edges or 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?

The description explicitly states that one of `event` or `topic` is required and warns that calling with no args fails. It gives clear recommendations for when to use each mode, including criteria like Jaccard similarity and placeholder filtering. It also explains the fill check to avoid trading unrealizable edges.

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

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

Annotations already mark the tool as readonly, open-world, idempotent, and non-destructive. The description goes far beyond this by detailing internal logic (three model families, caching strategy, diagnostic output, tradeable-edge knobs, and edge cases like Fed bets). It clearly states that the tool is cached 1h at KV level, that edge_pp_net is after slippage, and that a 24h-move warning appears when market movement erodes the edge. No contradictions with annotations.

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

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

The description is well-structured with section breaks and parenthetical clarifications, but it is extremely verbose – containing full explanations of model families, edge conditions, and diagnostic details that could be condensed or moved to documentation. While packed with useful information, it exceeds the brevity expected for a tool description, making it harder for an agent to parse quickly. Some details, like the exact Kelly caps and per-sport alpha values, are likely noise for selection purposes.

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 (9 parameters, no output schema, no nested objects), the description provides exhaustive coverage: it explains the response structure (by_segment, fed fields, diagnostics), caching behavior, and edge cases (e.g., partition placeholder filters, unreliable Fed signal without paid data). It also clarifies how tradeable-edge knobs interact with filtering. This ensures an agent can accurately predict the tool's behavior 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?

All 9 parameters already have schema descriptions (100% coverage). The tool description adds significant value by explaining the rationale behind each parameter's use – e.g., for 'min_liquidity' it suggests 'Set to 5000 to drop thin-book opportunities', for 'max_spread_pp' it recommends 'Set to 2 to require tight books', and for 'min_partition_leg_kelly' it clarifies why 'min_kelly' does not apply to partition arbs. These enrichments help the agent set knobs appropriately.

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, specific verb-resource pair ('Scan top Polymarket markets') and states the exact output ('return opportunities where Pipeworx data disagrees with market price'). It explicitly targets the use case 'what should I bet on today' and distinguishes from sibling tools by framing this as the primary opportunity discovery tool without paging through hundreds of markets.

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 the primary use case ('what should I bet on today') and provides context for when to employ this tool – for discovering opportunities where Pipeworx data disagrees with market price. It also includes a specific exclusion: Fed bets are surfaced but excluded from ranking due to unreliable signal without paid data, guiding agents not to rely on that output. However, it does not explicitly compare to sibling Polymarket tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) or state when to prefer them.

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

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

The description adds behavioral context beyond annotations: history depth bounded by 60-day TTL, decay from daily closes not intraday, and gaps indicate no scan. No contradiction with annotations.

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

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

The description is front-loaded with purpose and has a clear structure: concept, question, args, response fields, limits. However, it is somewhat verbose and could be more concise.

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

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

Given the complexity and lack of output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and limits. It is complete enough for an agent to understand what the tool returns.

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

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

Schema coverage is 100% with descriptions. The tool description largely restates parameter semantics (days lookback, default, max; window family, default). It adds minimal additional meaning beyond the schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots and answers a specific question about edge duration. It distinguishes from sibling polymarket_edges by focusing on historical persistence and decay.

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

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

The description implicitly guides when to use the tool by contrasting a fresh wide edge with a 3-week-old wide edge, indicating the tool helps assess decay. However, it does not explicitly state when not to use 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 declare readOnlyHint=true, idempotentHint=true, etc. The description adds rich behavioral context: walks the ladder, returns verdicts, warns about thin legs and unhedged directional risk. No contradictions; fully consistent.

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

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

Single dense paragraph, well-structured with caps for key terms (REQUIRES, SINGLE-MARKET, BASKET). Front-loaded with core purpose. Slightly verbose but 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?

Given the complexity (two modes, 4 parameters, no output schema), the description thoroughly explains both modes, return fields, and warnings. Complete enough for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions. The tool description adds operational context for side and size_usd in basket mode, and clarifies when to use market vs event. Not a 5 because some parameter info is already in schema.

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

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

The description clearly states it checks 'Realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes between single-market and basket modes. It lists specific return values and explicitly differentiates from siblings like polymarket_arbitrage and 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?

Provides explicit when-to-use guidance: before acting on arb signals or trades above $500. Explains both modes, defaults, and warns about risks of partial basket fills. Also states requirements ('REQUIRES one of market or event').

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

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

The description extensively covers behavioral traits beyond annotations: response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and the rarity of real spreads. It aligns with annotations (readOnlyHint, idempotentHint) and adds significant value.

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

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

The description is relatively long but well-structured with clear sections (modes, response, safety fields). Every sentence adds value, though some extraneous details could be tightened without losing 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 no output schema, the description thoroughly explains what the tool returns and covers edge cases (compatibility_warning conditions, temporal alignment). It is comprehensive for a complex tool with safety fields and multiple modes.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context by listing topic options, explaining override behavior, and providing examples. It enriches understanding beyond the schema alone.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on inter-venue comparison, and from other tools by its specific 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 explains two modes (topic and explicit) and warns that most pre-mapped topics are not tradeable, providing clear conditions for use. However, it does not explicitly name alternative tools for when this tool is unsuitable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: scoping to identifier (anonymous IP, BYO key hash, account ID), listing behavior when key omitted, and typical use cases (tickers, addresses, notes). No contradictions.

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

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

Two sentences, no waste. The main action is front-loaded. Each sentence provides distinct value: first sentence states behavior, second explains use case and scoping. Third sentence pairs with companions.

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 simple schema (1 optional param), no output schema, and annotations covering safety, the description covers retrieval and listing. It hints at return type ('value' or 'list of keys') but does not specify format. Adequate for 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 for the single optional parameter 'key' with description. The description reiterates the behavior (omit to list all keys) and adds examples in the schema, but no new semantic detail 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 states the tool's purpose with specific verbs ('retrieve', 'list') and resource ('value saved via remember', 'all saved keys'). It clearly distinguishes from siblings like 'remember' and 'forget' by specifying the action (retrieve vs save/delete).

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

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

The description gives context on when to use: 'look up context the agent stored earlier... without re-deriving it from scratch.' It pairs with remember/forget but does not explicitly say when not to use or list alternatives. However, the guidance is clear within the sibling context.

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

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

The description contradicts the readOnlyHint annotation by describing mark_read:true as a side effect that flags events as read, modifying state. This is a direct 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 and efficient, with no redundant information. Each 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?

The description covers most important aspects but omits two parameters and contradicts annotations, causing confusion about the tool's mutability.

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

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

The schema has 100% coverage, and the description adds meaning for 'type', 'since', and 'mark_read' (e.g., since is inclusive, mark_read affects subsequent calls). It omits 'limit' and 'unread_only', but the schema fills the gap.

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

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

The description clearly states the tool retrieves recent alerts from the subscription feed, listing key attributes (source, citation_uri, payload). It distinguishes from sibling tools by specifying it's for alert retrieval and even provides an alternative HTTP endpoint.

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 explains when to use (polling, filtering) and notes an alternative (HTTP endpoint). It doesn't explicitly state when not to use, but no direct sibling exists.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, destructiveHint. The description adds details about internal fan-out to SEC EDGAR, GDELT→GNews fallback, and USPTO soft-fail scenario, which goes beyond annotations and is not contradictory.

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, front-loaded with purpose and usage patterns. Every sentence adds value, with no wasted words. Length is appropriate 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?

Covers all aspects: what the tool does, sources, fallback, parameter formats, return structure (changes, total, URIs), and alternative tool. No output schema, but return structure is described. Complete for an agent.

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

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

Schema coverage is 100%, but the description adds extra context: examples of relative shorthand for 'since' (e.g., '30d', '1y'), a recommendation for typical monitoring, and clarifies that 'value' can be ticker or CIK. This enhances schema descriptions.

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

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

The description clearly states the tool provides a change feed for a company in a given time window, fanning out to multiple sources. It explicitly distinguishes from sibling 'entity_profile' by saying 'Use entity_profile instead when you want the static profile'.

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

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

Includes explicit usage examples like 'What's new with X', provides guidance on when to use the alternative tool (entity_profile), and describes fallback behavior (GDELT preferred, GNews when rate-limited).

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 cover idempotency and non-destructiveness; description adds scope (user identifier, persistent vs 24-hour retention). 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?

Five sentences, front-loaded with purpose. Informative without being verbose, though could be slightly tighter.

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 simplicity (2 params, no output schema), description covers usage, scope, retention, and siblings. Nothing missing for an agent to use correctly.

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

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

Schema already covers both params with descriptions. Description adds examples and clarifies scoping by identifier, enriching beyond schema.

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

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

Clearly states verb (save), resource (data), and scope (reuse later across conversations/sessions). Distinguishes from siblings recall and forget.

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

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

Explicitly tells when to use (discover something worth carrying forward) and mentions pairing with recall/forget. Lacks explicit when-not-to-use but provides strong situational guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by detailing the internal cascading (replaces 2-3 manual lookups) and specifying exact return fields per type (e.g., ticker, CIK, URI for company; RxCUI, ingredient for drug). 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 paragraph that front-loads usage examples and then explains supported types. It is efficient but could be more structured (e.g., bullet points for each type). Every sentence earns its place.

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

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

Despite no output schema, the description thoroughly explains return values for both entity types. It covers behavior, input, output, and usage context. No gaps given 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%, but the description adds significant meaning: it explains acceptable input formats per type (e.g., for company: ticker, CIK, or name; for drug: brand/generic) with concrete examples ('AAPL', 'ozempic'). It also mentions auto-disambiguation for company input, going well beyond the schema.

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

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

The description clearly states the tool resolves names to canonical identifiers, with specific examples ('ticker for', 'CIK for', 'RxCUI for'). It distinguishes from siblings by listing supported entity types and describing the cascading internal lookups that replace multiple manual steps.

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 FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It does not explicitly state when not to use or list alternative tools, but the context is clear.

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

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

Annotations already provide readOnlyHint etc. Description adds specifics: probes each entity, ranks by score, returns score/confidence/signal density. No contradiction.

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

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

Two sentences, front-loaded with purpose and behavior. No wasted words. Efficient.

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

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

Describes output (ranked list with score, confidence, signal density). Covers required and optional params. Lacks error cases or limits, but acceptable for a read-only probe 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% (baseline 3). Description adds meaning: first entity treated as subject, context disambiguates common names. 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check. Differentiates from single-probe sibling by mentioning multiple entities and ranking.

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 use case (competitive AI-marketing audits) but does not explicitly state when not to use or name alternatives. Implicitly contrasts with ai_visibility_check.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description discloses potential latency for bundlephobia's first measurement (5-30s), partial failure behavior (sources_failed field), and graceful degradation. 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 dense paragraph that front-loads the main purpose. Every sentence adds value, but a more structured format (e.g., bullet points for return fields) could improve readability. Still concise with no wasted words.

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

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

With no output schema, the description fully explains return values (summary block, per-advisory detail, links, alternative versions). It also covers edge cases like partial failures and ecosystem limitations, making it complete for agent invocation.

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

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

Schema coverage is 100%, with clear descriptions for both parameters. The description does not add new semantics beyond what the schema provides, but it contextualizes how parameters are used in the composite call. A score of 3 is appropriate based on 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 it's a composite check for evaluating npm packages, combining deps.dev and bundlephobia. It specifies the verb and resource, and the purpose is unambiguous. It distinguishes from siblings by being the only tool for dependency scanning.

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".' Also specifies that it's npm-only and provides direct alternatives for other ecosystems (PyPI, Maven, etc.), giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond the readOnlyHint annotations, the description discloses truncation at 200K chars, embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, and the inclusion of offsets. No contradictions with annotations.

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

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

The description is concise with 4 sentences, each adding meaningful information. It could be very slightly trimmed but is well-structured and front-loaded.

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

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

For a tool with no output schema, the description adequately explains what is returned (passages with offsets and scores), the 200K char limit, and the underlying retrieval method. The context signals (3 params, high schema coverage) complement the description well.

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, but the description enriches understanding by explaining the role of each parameter (e.g., 'text you already pulled', 'natural-language query') and the internal mechanism, adding value beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, returning top-N passages with character offsets and similarity scores. It distinguishes itself from sibling tools by explicitly pairing 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 tells when to use ('when the record is too big to cram into the prompt') and mentions a complementary tool (ask_pipeworx_grounded) for grounding. This provides clear usage context and alternatives.

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

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

The description adds significant behavioral context beyond annotations: requires OAuth account, delivery channel specifics (SMS verification with cap, webhook auto-disable after 10 failures), and persistence requirements. It also clarifies the return value. No contradiction with annotations.

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

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

The description is well-structured with the main action first, then prerequisites, then types and delivery channels. It is somewhat long but every sentence is informative. Minor redundancy could be trimmed but overall efficient.

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

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

Given the complexity (nested params, no output schema), the description covers input parameters thoroughly, explains return value, prerequisites, limitations, and even mentions companion tools (recent_alerts). It is nearly complete for effective 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?

Despite 100% schema coverage, the description provides rich type-specific examples (e.g., sec_8k items codes, fred_series series_id) and delivery channel details (email pattern, webhook signing). These add meaning beyond the schema's terse descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The verb 'Create' and resource 'subscription' are specific.

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

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

The description provides prerequisites (requires Pipeworx OAuth account) and some limitations (e.g., SMS cap of 10/day). However, it does not explicitly instruct when to use this tool versus alternatives like list_subscriptions or recent_alerts. The guidance is implicit rather than explicit.

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

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

Annotations readOnlyHint=true, idempotentHint=true, destructiveHint=false clearly indicate safe read behavior. The description adds valuable behavioral context: it is the onboarding entry point, returns a structured output (category-bucketed examples), and can be called with or without a topic. No contradiction.

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

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

The description is front-loaded with common user queries and is well-structured. It is slightly long but every sentence adds value. The list of categories and the guidance on usage are efficiently packed.

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

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

Given no output schema, the description thoroughly explains the output format (category-bucketed examples with tool+argument shapes) and the tool's purpose as an onboarding entry point. It is complete and contextually appropriate among 30+ sibling tools.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by explaining the topic parameter's allowed values (e.g., 'finance', 'pharma') and that omitting it gives a full cross-category spread. This goes beyond the schema's description.

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

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

The description clearly states the tool returns category-bucketed example questions to help users understand what Pipeworx can do. It uses specific verbs ('returns', 'learn how to call') and explicitly defines the resource (example questions with tool+argument shapes). It distinguishes from siblings as the onboarding entry point.

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

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

The description provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also tells when to pass the topic parameter and when to omit it. It hints at alternatives by mentioning meta-tools like ask_pipeworx, entity_profile, etc., giving clear context for usage.

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

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

The description goes beyond annotations by explaining that the row is deactivated (not deleted), keeping historical events available. This aligns with the annotations (destructiveHint=false, idempotentHint=true) and adds valuable behavioral context.

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

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

The description is extremely concise with two sentences, no wasted words. The first sentence immediately states the core function, making it front-loaded and efficient.

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

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

For a simple tool with one parameter, no output schema, and well-annotated metadata, the description provides complete context: what it does, ownership constraint, soft-delete behavior, and link to 'recent_alerts' for historical data.

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

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

Schema description coverage is 100% for the single parameter 'id' (described as 'Subscription id (uuid) returned by subscribe.'). The description does not add additional meaning beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the action ('cancel a subscription by id') and the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying the cancellation operation and ownership enforcement.

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

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

The description provides clear context: ownership is enforced, so only own subscriptions can be cancelled. It implies when not to use (if not own subscription) and references 'recent_alerts' for historical events, but does not explicitly name an alternative tool for non-own 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?

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: returns verdict (confirmed/refuted etc.), structured form, actual value with citation, percent delta, and uses SEC EDGAR + XBRL. No contradictions with annotations.

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

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

The description is concise yet packed with useful information: examples, domain, return structure, efficiency claim. Every sentence serves a purpose, and it's well-structured with front-loaded usage patterns.

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 one parameter and no output schema, the description is remarkably complete. It explains return format, data source, supported claim types, and limitations (v1 supports company-financial claims). Annotations complement the description well.

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

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

Schema coverage is 100% with one required parameter 'claim' that has a description. The description expands on this by providing natural-language usage examples, specifying the domain (company-financial), and clarifying the expected format of claims, adding substantial meaning beyond the schema.

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

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

The description clearly states it validates natural-language factual claims against authoritative sources, with specific supported domain (company-financial claims). It includes example phrasings ('Is it true that…', 'fact check') and explicitly distinguishes from siblings like deep_research by noting it replaces 4-6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct' and specifies the supported domain (company-financial claims). While it doesn't list alternatives or when-not-to-use, the context is clear given the sibling tools.

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