Hubspot

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

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds further context: default model is free, Anthropic requires BYO key, and return structure is described (score, confidence, etc.). 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 coherent paragraph with no wasted words. It front-loads the primary action and provides essential details efficiently. Could be slightly improved with bullet points, but overall 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?

No output schema exists, but the description adequately describes the return format. The tool has 4 parameters with one required, and the description covers all key aspects (purpose, parameters, use cases). Complete enough for an AI agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful examples and explanations for each parameter (e.g., 'entity' examples, 'context' for disambiguation), enhancing understanding beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It differentiates itself from sibling tools like 'ask_pipeworx' by focusing on AI visibility rather than general queries.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the _apiKey. It does not explicitly exclude 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the tool's internal behavior: routing to 3,751 tools across 886 sources, filling arguments, and returning structured citations. This adds significant 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 front-loaded with the key directive 'PREFER OVER WEB SEARCH' and then lists many examples, making it somewhat long but highly informative. It is well-structured but could be slightly shortened.

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

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

Given the tool's complexity (3,751 tools, 886 sources) and absence of output schema, the description thoroughly explains the return format (structured answer with citation URIs) and covers a wide range of use cases, making it fully complete for an agent to understand.

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 6 parameters all described as aliases for 'question'. The description adds meaning by explaining the question parameter accepts natural language and provides examples. While baseline is 3 due to high coverage, the extra examples and aliases add value, earning a 4.

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

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

The description clearly states it routes questions to a large collection of tools for structured authoritative data, distinguishing it from web search with specific use cases like SEC filings, FDA data, etc. It provides strong differentiation from sibling tools.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and provides detailed guidance on when to use it (factual questions about real-world entities, events, numbers) with concrete examples. It helps the agent make a decision to use this tool over alternatives.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds substantial context: costs one extra LLM call, returns explicit refusals with structured reasons (refusal_reason enum), and extracts answer using only tool result. 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 slightly long but front-loaded with purpose and key differentiator. Every sentence adds value: purpose, process, output format, usage guidance, and cost tradeoff. Could be marginally shorter, but still efficient.

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

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

For a complex tool with no output schema, the description fully covers return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. It also explains the extra LLM call cost and comparison with sibling. Comprehensive and actionable.

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

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

Input schema has 6 parameters, all aliases for 'question', with 100% description coverage. The description mentions that it accepts aliases like 'query, q, prompt, text, input', but this is already present in the schema. No additional semantic value beyond schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads', specifies its routing and extraction process, and distinguishes it from sibling 'ask_pipeworx' by noting the extra extraction step. The verb 'extracts' and resource 'answer from tool result' are specific.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups', providing clear when-to-use and when-not-to-use guidance. Also explains the cost tradeoff.

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=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: fan-out patterns, response shapes, resolver contract, parent event extractor, news fallback fields, safety short-circuits for low-confidence matches, wide-spread market handling, and resolution-rule risk. This goes well beyond annotation hints.

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

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

The description is long but highly informative. It front-loads the main purpose and usage, then details various behavioral aspects. While every sentence adds value, it could be slightly more condensed without losing critical 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 complexity (3 params, no output schema, rich internal logic), the description covers all essential aspects: input types, fan-out categories, response shapes, resolver contract, parent event extraction, news fields, safety checks, and resolution rules. 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% (all 3 parameters documented). The description adds meaning beyond schema: clarifies 'market' accepts slug, URL, or question text; explains 'depth' values (quick vs thorough); details 'include_raw' effect (summarized vs full payloads).

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 researches Polymarket bets by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like 'polymarket_edges' or 'polymarket_arbitrage' which focus on edge scanning or arbitrage, not comprehensive research.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. Provides examples of when to use. However, it does not explicitly state when not to use, nor does it mention alternatives like 'polymarket_edges' for edge analysis only.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs.

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

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

The description is detailed and well-structured, starting with example queries, then entity-specific behavior, then sorting and output. Every sentence adds value, though it could be slightly shortened without losing meaning. Still, it's appropriately front-loaded and informative.

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 entity types, multiple data sources, citation URIs), the description covers all needed aspects: input format, data retrieved, sorting behavior, and output format. With no output schema, it explains return values (paired data + URIs). Parameters are fully documented in schema and description.

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

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

Schema coverage is 100%. The description adds significant meaning beyond the schema: for type 'company', it explains values are tickers/CIKs and what financial metrics (10-K revenue, net income, etc.) are retrieved; for type 'drug', it explains values are drug names and what counts (adverse events, FDA approvals, trials) are fetched. This clarifies parameter usage and expected output.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific examples of queries like 'which is bigger / better' and 'head to head'. It distinguishes itself from sequential lookups and specifies the data sources per entity type.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a strong when-to-use guideline. It does not explicitly mention alternatives like entity_profile for single entities, but the context implies that.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds details: returns verbatim evidence, confidence, source, fetched_at, stable citations, explicit gaps for unanswered facets, never invents. Also mentions account requirements and expected duration.

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 each sentence adding value. It is front-loaded with the core function. Could be slightly shorter, but no wasted words.

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

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

Given the tool's complexity, the description is thorough: explains process, output format (findings packet), edge cases (gaps), prerequisites (account), timing (15-60s), and contrasts with sibling. No output schema, but description covers return values 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 covers 100% of parameters. Description adds value by explaining depth values as 'quick=3, standard=5, thorough=8' and linking to paid plans, and clarifies the question parameter accepts broad/multi-part queries.

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

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

The description clearly states the tool performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to many tools. It distinguishes itself from sibling ask_pipeworx for single lookups.

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

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

Explicitly advises use for broad or multi-part questions with examples, and tells when to use ask_pipeworx instead. Provides clear when-to and when-not-to guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This adds value 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 a single, well-structured paragraph that front-loads the core purpose. It is concise while providing necessary details about domains, return format, and usage guidance. No wasted words.

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

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

Given high schema coverage, clear annotations, and no output schema, the description fully covers the tool's behavior. It explains when to use, what it returns, and how to call it. The AI agent has all necessary context to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema fully documents all parameters. The description provides context for the 'query' parameter with examples and the phrase 'Natural language description,' adding some semantic value beyond the schema. However, it largely repeats what's in the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains and use cases. It distinguishes itself from sibling tools by positioning itself as a meta-tool for discovery, explicitly saying 'Call this FIRST when you have many 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 states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for:' with domain examples. It also implies a first-step usage: 'Call this FIRST when you have many tools available and want to see the option set.' However, it does not explicitly exclude scenarios or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: parallel fan-out across sources, USPTO API sunset soft-fail, GDELT→GNews fallback, and detailed output structure. No contradictions.

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

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

The description is concise and well-structured. It starts with example queries and usage guidance, then details the fan-out behavior and return fields. Every sentence adds value, and it is appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains all return fields (cik, filings, fundamentals, patents, news, LEI). It covers edge cases like the USPTO API sunset and provides URI examples. The tool is complex, and the description is complete.

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

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

Schema coverage is 100%. The description adds valuable meaning beyond the schema by explaining accepted values (ticker or CIK), providing examples, and clarifying that names are not supported. It also describes the enum constraint on type.

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 defines the tool's purpose: providing a full cross-source profile of a US public company. It includes example queries and lists the specific data sources and return fields, distinguishing it from siblings like resolve_entity and compare_entities.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and when not to use it ('names not supported — use resolve_entity first'). It provides clear context for selection.

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

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

The description says 'delete', matching the destructiveHint annotation. It does not add behavioral context beyond what annotations provide (destructive, idempotent). No contradiction. Adequate but no extra 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?

Two sentences, no fluff. First sentence states purpose, second provides usage guidance. 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 delete operation with one parameter and clear annotations, the description covers purpose and usage. Could mention irreversibility or undo, but overall sufficient.

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

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

Schema coverage is 100% and describes the 'key' parameter. The tool description does not add any additional meaning beyond the schema definition.

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 'Delete a previously stored memory by key', which is a specific verb and resource. It clearly distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. Also suggests pairing with siblings. Does not explicitly mention when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context (fetches page, extracts title/description/key links) without contradicting annotations. It does not mention rate limits or auth, but annotations suffice.

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

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

The description is two sentences with no fluff: first sentence defines purpose and output, second lists use cases. Every word adds value, and the structure is front-loaded with key action.

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

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

For a simple tool with 2 parameters and no output schema, the description covers purpose, process, output format, and use cases. It is self-contained and sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, and the description essentially repeats the schema for both parameters ('url' and 'max_links'). No additional semantic value beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for AI crawler indexing, specifying the process (fetches, extracts, emits) and the output format. It distinguishes itself from unrelated sibling tools by its unique 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 lists explicit use cases (client indexing, own project drafting, competitor auditing) and implies when to use it. It does not mention when not to use or alternatives, but the context is clear given the tool's specificity.

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. Description adds value by specifying return fields (name, domain, industry, revenue, custom properties) beyond what annotations provide, but does not contradict 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 efficient sentences with no fluff. The purpose and return info are 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 simple get-by-ID tool with 1 parameter, output schema, and comprehensive annotations, the description adequately covers purpose and return information.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds no further meaning to the parameter 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?

Clearly states the tool fetches a company's full profile by ID, listing returned fields (name, domain, industry, revenue, custom properties) and distinguishing from sibling tools like hs_get_contact and hs_get_deal.

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., hs_list_companies for listing). The description implies usage when a company ID is known, but lacks when-not or sibling differentiation.

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, etc. The description adds that custom properties are returned, which is useful but not extensive. No behavioral traits beyond annotations are disclosed.

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?

A single, clear sentence that immediately conveys the tool's purpose. No wasted words, and the most critical information is 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 simple read-only tool with one parameter and an output schema, the description sufficiently explains what the tool returns (specific fields and custom properties), leaving no gaps.

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

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

Schema coverage is 100%, and the schema already describes the 'id' parameter as 'HubSpot contact ID'. The description only mentions 'by ID' without adding new semantics, so baseline of 3 is appropriate.

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

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

The description clearly states the action ('fetch'), the resource ('contact's full profile'), and the method ('by ID'). It lists the fields returned, which distinguishes it from sibling tools like hs_list_contacts and hs_search_contacts.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools such as hs_search_contacts and hs_list_contacts exist, but the description does not provide context for choosing among 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?

Annotations already indicate readonly, idempotent, non-destructive. Description adds value by specifying returned fields and linked entities, complementing annotations without contradiction.

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

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

Two sentences, no filler, verb-first, efficient delivery of key information.

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

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

Simple tool with output schema; description fully covers purpose and return values. No gaps given the tool's simplicity.

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?

Single parameter with 100% schema description coverage ('HubSpot deal ID'). Description merely references 'by ID' without adding new semantics 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?

Clear verb 'Fetch', specific resource 'deal', and details the returned fields (name, amount, stage, owner, linked entities). Distinguishes from sibling list tools and get tools for other entities.

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

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

Implies usage when full details of a specific deal are needed, but does not explicitly contrast with alternatives like hs_list_deals for listing or hs_get_company for company details.

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 concrete behavior: returns company IDs, names, domains, properties, and supports pagination with limit/after. Adds value beyond annotations.

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

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

Two efficient sentences: first states purpose, second states output fields and pagination. No extraneous words, front-loaded key information.

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

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

With output schema present, return values are covered. Description specifies returned fields and pagination. Lacks details like default sort order or field types, but acceptable for a list tool with rich annotations and schema.

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

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

Schema coverage is 100% with descriptions for both parameters. Description mentions pagination but does not add new semantic details beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly states verb 'Browse' and resource 'companies in your HubSpot workspace', and specifies return fields. It distinguishes from siblings like hs_get_company (single) and hs_search_contacts (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?

Implies use for browsing all companies, but does not explicitly state when to use vs alternatives like hs_get_company or hs_search_contacts. No when-not or alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description carries less burden. It adds value by stating pagination behavior (limit and after parameters). 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, front-loaded with purpose. Every sentence adds necessary information (purpose, return fields, pagination). No fluff.

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

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

With an output schema present, the description does not need to detail return structure. It covers all needed aspects: what the tool does, what it returns, and how to paginate. Completely adequate for a list tool given the rich annotations and schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description only reiterates that parameters support pagination, which is already in the schema. No additional meaning beyond schema is provided.

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

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

The description uses a specific verb 'Browse' and resource 'contacts' to clearly state the tool's purpose. It lists returned fields (IDs, names, emails, properties) and distinguishes from sibling tools like hs_get_contact (single contact) and hs_search_contacts (filtered search) by implying a full listing.

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

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

The description implies usage for browsing all contacts with pagination. While it does not explicitly state when not to use or mention alternatives, the context of sibling tools (e.g., hs_search_contacts for filtering) is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so safety is clear. The description adds pagination behavior (limit and after), but does not disclose rate limits or other side effects, earning a score of 3.

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 covers purpose and output, second covers pagination. No redundant information, front-loaded with key details.

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

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

Given the simple list tool with full schema coverage, annotations, and an output schema, the description adequately covers purpose, returned fields, and pagination, requiring no further explanation.

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

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

Schema coverage is 100%, and the description merely restates pagination with limit and after without adding new semantic value beyond what the schema already provides. Defaults and max are already in the schema.

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

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

The description clearly states the verb 'browse' and resource 'deals', specifies the workspace scope, and lists returned fields (IDs, names, amounts, pipeline stages, close dates), making it highly specific and distinguishable from sibling list tools like hs_list_contacts.

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 use when needing to view all deals, but lacks explicit guidance on when not to use it (e.g., for searching or filtering) or references to alternatives like hs_get_deal for single deals.

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, and openWorldHint, so the description's behavioral burden is reduced. It adds that search can be by name, email, or custom properties, but does not disclose pagination behavior or result limitations beyond the schema's limit parameter.

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

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

Two sentences front-loaded with action. No wasted words.

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

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

Given the presence of output schema (not shown but indicated) and rich annotations, the description covers purpose, search criteria, and usage context adequately. No obvious gaps for a search tool.

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

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

Schema coverage is 100% (both parameters described), so baseline is 3. The description adds value by specifying that query can be name, email, or custom properties, which is not in the schema. It does not detail custom properties syntax, but this is acceptable.

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

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

The description explicitly states 'Search contacts by name, email, or custom properties' with a clear verb ('search') and resource ('contacts'). It distinguishes from sibling tools like hs_get_contact (retrieve single) and hs_list_contacts (list all) by specifying the search 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 says 'Use when you need to find specific people in your database,' providing clear context. However, it does not explicitly state when not to use it or mention alternative tools like hs_get_contact for exact lookups.

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, indicating a safe read operation. The description adds value by listing the specific fields returned (id, type, params, created_at, last_fired_at, fire_count), which is helpful beyond annotations.

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

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

Two sentences, no wasted words. Purpose is front-loaded, and every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description sufficiently covers the returned fields and usage context, making it complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with the 'include_inactive' parameter fully described. The description does not add extra semantics beyond what's in the schema, meeting the baseline for high coverage.

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

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

The description explicitly states 'List the caller's active subscriptions' with a clear verb (list) and resource (subscriptions). It distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

Provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use the tool, though it 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?

The description discloses rate limits (5 per identifier per day), that it is free and doesn't count against quota, and that feedback is read daily and affects roadmap. Annotations are all false, so description 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 compact and front-loaded with the main purpose. Every sentence provides value 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?

Given no output schema, the description explains what happens to feedback (read daily, affects roadmap), rate limits, and quota implications. It fully covers the tool's purpose and how to provide effective feedback.

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

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

Schema coverage is 100%, but the description adds meaning by explaining each feedback type and advising to describe issues in terms of Pipeworx tools/packs without pasting end-user prompts. It could further detail the optional context fields.

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 for sending feedback about bugs, missing features, data gaps, or praise to the Pipeworx team. It distinguishes between these types and differentiates from sibling tools (none of which are feedback 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 the tool (bug, feature request, data_gap, praise) and notes it is free and quota-free. It does not list when not to use it, but the context makes it clear this is a feedback-only tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds caching behavior (5min-1h), data source (CF analytics-engine), privacy (no PII), and output components (pack, tool, count). No contradictions.

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

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

Description is a single paragraph but all sentences add value: main functionality, use cases, caching details. No redundancy, but could be more succinct for a simple tool.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully explains what it returns, when to use, and caching behavior. 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 one parameter (window). The description adds context: shorter windows surface hot trends, longer show steady-state demand. This enriches the enum values beyond the schema description.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. This distinguishes it from siblings like search tools or entity profiles. The first sentence uses a specific verb ('returns') and resource ('top tools, top packs, total call volume').

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 given: discovering hot data sources, confirming canonical tool, and checking alignment. It also mentions self-aggregating signal and caches. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds details about internal checks (monotonicity, partition, similarity, fill check), constraints (Jaccard similarity, placeholder filter), and failure modes. 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?

Long but well-structured: begins with requirement, then explains modes, then algorithmic details, then output fields. Effective front-loading but some details (e.g., fill check) 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?

With no output schema, description adequately explains return fields (opportunities, partition_check, fill_check). Covers inputs, behavior, constraints, and edge cases. Sufficient for an agent to understand and 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 both parameters described in schema. Description adds deep semantics: mode selection, example values, behavior differences, and algorithmic details (Jaccard threshold, partition filter). Adds significant value beyond schema.

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

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

The description precisely states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes, each with specific use cases and examples.

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

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

Explicitly states when to use event vs topic, including that calling with no args fails. Provides examples and notes alternatives like polymarket_fill_risk for custom sizing. Clear 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?

The description goes far beyond annotations, which already indicate read-only, idempotent, and non-destructive behavior. It discloses caching ('Cached 1h at the KV level keyed on all knobs'), explains the three model families in detail, and documents edge calculation, slippage, Kelly sizing, and tradeability filters. It also transparently notes the Fed data unreliability and diagnostic fields. 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 very detailed and dense, which is appropriate given the tool's complexity (9 parameters, multiple model families). It is front-loaded with the core purpose and structured into sections for model families, knobs, and response format. However, it could be slightly more concise by reducing some of the technical model details that may be redundant for an AI agent. Nonetheless, every sentence adds value.

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

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

For a tool with 9 parameters, no output schema, and high complexity, the description is exceptionally complete. It explains the response structure (by_segment, fed_candidates, _diagnostics), caching behavior, how to interpret keys like edge_pp_net and kelly_fraction, and even how to debug empty segments. It covers all aspects an agent would need to invoke and understand 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?

Although schema coverage is 100%, the description adds significant value beyond schema descriptions. It provides practical usage advice for each parameter, such as 'Bump for very thin partitions; drop to 0 if you have a smarter fill model' for slippage_pp, and explains the interplay between parameters like min_kelly and min_partition_leg_kelly. Examples and defaults are included, making the semantics rich.

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

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

The description starts with a specific verb-object pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's purpose and distinguishes it from siblings like polymarket_arbitrage, which focuses on pure arbitrage. The phrase 'Built for "what should I bet on today"' further clarifies the intended use case.

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

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

The description explicitly states when to use this tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains how to adjust tradeability via knobs like min_liquidity and max_spread_pp, and provides diagnostic information (e.g., _diagnostics) for when a segment is empty. This gives clear guidance on when and how to use the tool, including limitations like Fed data exclusion.

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

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

The description adds significant behavioral context beyond annotations: it explains the read-only nature, details the response structure (tracked, expired, snapshot_dates), and clarifies that decay is from daily closes, not intraday. It does not contradict any annotations.

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

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

The description is front-loaded with the core purpose, then details response fields, then limits. It is slightly long but every sentence is informative. Could be slightly more concise by separating the response structure, but overall well-structured.

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

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

Without an output schema, the description fully explains the return value: tracked items with time-series, first_seen, trend, decay; expired items with lifespan_days; snapshot_dates. It also covers limitations (60-day TTL, snapshot start). Very complete for a tool with two optional parameters.

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 both parameters are already well-documented in the schema. The description reiterates defaults and adds a clamp range for 'days' and mentions the window family, but adds minimal extra semantic value beyond what the schema provides.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It uses a specific verb ('answers') and resource ('edge persistence and decay telemetry'), and distinguishes itself from sibling polymarket_edges by emphasizing temporal context.

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

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

The description provides clear context on when to use the tool: to understand if an edge is new or old, which affects trading decisions. It includes limits (60-day TTL, snapshot start date) but does not explicitly name alternative tools or state when not to use it.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it walks the order book ladder, returns specific fields like slippage_pp, verdict, thin legs, and forced directional risk. It does not contradict annotations.

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

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

The description is relatively long but well-structured: it starts with the core purpose, then explains two modes with bullet-like detail, and ends with usage guidance. Every sentence adds value given the tool's complexity. Could be slightly shortened without losing information, but still 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 thoroughly explains all return values for both modes, including edge cases like thin_legs and forced_directional_risk. It also covers default values and clamping for size_usd. This is highly complete for a tool with 4 parameters.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: it explains the different interpretation of size_usd for single-market vs basket, the auto side logic for basket, and the requirement that exactly one of market or event is provided. It also lists return fields that depend on parameters.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes: single-market and basket. It explicitly references sibling tools polymarket_arbitrage and polymarket_edges, telling when to use this tool before acting on them.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.

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 details safety fields like compatibility_warning with two cases, temporal_alignment, and skipped counters. It explains the conditions under which spreads are meaningless, providing rich 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 well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. While it contains some redundancy (e.g., listing topic values already in the schema), the organization compensates for minor verbosity.

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?

In the absence of an output schema, the description thoroughly explains the response structure including leg-by-leg prices, matched spreads, and all safety fields. It covers edge cases like compatibility warnings and temporal alignment, 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?

With 100% schema coverage, the description adds value by explaining the two modes (topic vs explicit parameters) and how explicit parameters override topic-mapped sides. It clarifies the relationship between parameters beyond what the schema provides.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like 'polymarket_arbitrage' which focuses on intra-venue arbitrage. It specifies two modes and details the output structure.

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 the tool (to compare same-outcome probabilities across venues) and warns that pre-mapped topics often yield compatibility warnings, meaning not all queries produce tradeable spreads. It does not explicitly name alternatives but provides clear context for decision-making.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping to identifier and typical use cases, without contradicting annotations.

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

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

The description is extremely concise: two sentences that front-load the main action and purpose. Every sentence adds value without 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?

Given the simple tool with one optional parameter and no output schema, the description is complete. It explains what the tool does, how to use it, and its scope.

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 description for the 'key' parameter. The description adds meaning: 'omit to list all keys' and explains the parameter's role, which is clear and helpful.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. It specifies the verb 'retrieve' and resource 'a value previously saved via remember', and distinguishes from siblings like remember and forget by naming them.

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

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

The description explains when to use the tool: to look up context stored earlier without re-deriving. It also mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it or alternatives beyond those 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 indicate read-only and idempotent behavior. The description adds that mark_read=true flags events as read, affecting subsequent calls, which is a side effect beyond annotations. It also notes the feed is persisted, adding transparency.

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

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

Four concise sentences front-loading purpose, then content, filters, and usage guidance. No wasted words; every sentence adds value.

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

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

The description covers most key aspects (purpose, returned fields, filters, polling, alternative endpoint). However, it omits mention of the 'limit' and 'unread_only' parameters, though they are fully described in the schema.

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

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

Schema coverage is 100%. The description adds semantic context by explaining filter parameters (type, since) with examples and the effect of mark_read, enhancing understanding beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returns most recent alerts, and lists key fields (source, citation_uri, raw payload). It differentiates from siblings like recent_changes and list_subscriptions by specifying it's for subscription alerts.

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 mentions polling works fine and provides an alternative HTTP endpoint, giving context for when to use this tool vs direct access. However, it does not explicitly exclude alternatives or contrast with sibling 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?

Discloses fan-out to SEC, GDELT→GNews fallback, USPTO soft-fail, return structure, and `since` format. Annotations confirm read-only, idempotent, non-destructive; description adds behavioral details.

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

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

Packed with information, front-loaded with example queries. Slightly long but every sentence adds value; could be tightened slightly.

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

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

Covers all parameters, use cases, fallbacks, and return structure. No missing information given the complexity. Output schema not needed due to description.

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

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

Schema coverage is 100%, but description adds value: explains `type` limited to 'company', `value` as ticker/CIK, `since` with formats and typical usage ('30d' for monitoring).

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 change feed for a company, listing SEC, news, and patents. It distinguishes from sibling 'entity_profile' which provides 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?

Explicitly says to use 'entity_profile' for static profile, provides example queries, and explains the fan-out behavior. 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 declare idempotentHint=true and destructiveHint=false. The description adds critical behavioral context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This goes beyond annotations and is accurate.

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 and well-structured: it leads with purpose, then usage, then behavioral details. Every sentence adds information without redundancy.

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

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

For a simple 2-parameter tool with no output schema and clear annotations, the description fully covers purpose, usage, behavior, and parameter meaning. No gaps remain.

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 adds value by providing example keys and clarifying that value is 'any text', which builds on 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: 'Save data the agent will need to reuse later' as a key-value pair. It uses a specific verb ('save') and resource ('data for later reuse'), and distinguishes from sibling tools like 'recall' and 'forget'.

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

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

The description provides clear guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with recall and forget, but doesn't explicitly cover when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and idempotency. The description adds that each call cascades through several endpoints and replaces manual lookups, providing some behavioral context but not contradicting annotations.

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

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

The description is well-structured and front-loaded with example queries and core purpose. It is slightly verbose but every sentence adds value, detailing supported types and return values. Minor redundancy in listing types twice could be tightened.

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

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

Despite no output schema, the description fully explains the return values for each entity type, including the specific identifiers and citation URIs. This ensures the agent knows what to expect. The tool is simple with 2 parameters, and the description covers invocation, types, and outputs completely.

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

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

Schema coverage is 100%, but the description adds significant meaning: for 'company' it explains return includes ticker, CIK, company name, and citation URI; for 'drug' it lists RxCUI, ingredient, brand, and citation. It also clarifies acceptable input formats for both types.

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 user-spoken names to canonical identifiers, with examples like 'What's the ticker for...'. It distinguishes itself from siblings by positioning as the go-to tool when an ID is needed and other tools require IDs as 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 explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It lacks explicit when-not-to-use scenarios or alternative tools, but the context strongly implies that tools like entity_profile are for when an ID is already available.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. Description adds value by explaining the internal process (probing each entity with ai_visibility_check, ranking by score) and the return content (score, confidence, signal density). 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 concise with four sentences, front-loaded with the main purpose, and each sentence adds value. No fluff or repetition of schema fields.

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 (4 parameters, no output schema), the description is very complete. It explains what the tool does, how it works internally, and what it returns (score, confidence, signal density). It also clarifies parameter usage. The annotations cover safety, so no further behavioral info needed.

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

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

Schema description coverage is 100%, but description adds important context beyond schema: the 'entities' first entry is treated as subject for narrative, 'models' and '_apiKey' relationship is clarified, and 'context' is explained as disambiguation. This adds significant meaning for correct usage.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, with a specific verb and resource. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by detailing that it probes each entity with ai_visibility_check and ranks them.

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

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

Description explicitly states it is useful for competitive AI-marketing audits and provides an example question. While it implies when to use, it does not explicitly state when not to use, though the context of comparing multiple entities versus single checks is clear from the sibling tool presence.

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 significant behavioral details: composite fan-out, timing for bundlephobia's first measurement (5-30s), graceful degradation with sources_failed key, and output structure. 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 detailed but every sentence contributes: purpose, usage guidance, return fields, limitations, and error behavior. It is front-loaded with the main function. Could be slightly more compact, but no redundant content.

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

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

Given the absence of an output schema, the description thoroughly explains the return structure (summary block fields like is_latest, license, advisory_count, bundle sizes, etc.) and acknowledges limitations (NPM only, partial failures). For a moderately complex composite tool, this provides full context for an agent to invoke it 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 provides additional value: clarifying that scoped packages like '@types/node' are accepted and that version defaults to latest when omitted. This adds nuance beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: a composite check for npm packages across deps.dev and bundlephobia. It explicitly distinguishes from other ecosystems (PyPI, Maven, etc.) and mentions sibling tools like deps.dev:version for those. This provides a specific verb and resource, making it clear and distinct.

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

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

The description explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use (NPM only; other ecosystems fall under deps.dev:version directly). It also notes partial failure behavior, giving clear context for appropriate selection.

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

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

The description adds rich behavior beyond annotations: BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flagging, and character offsets in results. 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 a single paragraph but is well-structured, starting with purpose. Every sentence adds information, though it could be slightly 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?

Despite no output schema, the description fully explains return format (passages with offsets and similarity scores) and how results can be used (verify verbatim quotes). Covers complex tool completely.

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

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

Schema coverage is 100%, but description adds value with examples for query and constraint for text (max 200K chars). It explains the purpose of each parameter beyond 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 it performs semantic search inside a fetched record, distinguishing it from siblings by mentioning its pairing with ask_pipeworx_grounded. It uses specific verbs and resources.

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

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

The description explains when to use (when record is too big for prompt) and mentions an alternative tool (ask_pipeworx_grounded). It does not explicitly state when not to use, 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=false (write operation), destructiveHint=false, idempotentHint=true. The description adds crucial behavioral context: OAuth requirement, return of subscription id, type-specific parameters, delivery channel constraints (email, SMS cap, webhook signing/auto-disable). 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 lengthy but well-structured, front-loading the main purpose and then detailing types and delivery. Every sentence adds value, though some redundancy exists (e.g., SMS details repeated). It could be slightly 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 the complexity (3 parameters, nested objects, no output schema), the description covers all aspects: security, return value, type-specific filters, delivery options with limitations, and failure handling (webhook auto-disable). It is complete for the agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. However, the description significantly adds meaning: it explains the 'type' enum values (e.g., sec_8k items), provides detailed examples for 'params' per type, and elaborates on 'delivery' fields (SMS verification, webhook signing secret). This goes well beyond the schema.

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

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

The description uses a specific verb-resource pair ('Create a proactive monitoring subscription to a live-data event stream') and explicitly distinguishes the tool from siblings like 'unsubscribe' (reverse operation) and 'list_subscriptions' (listing). The purpose is clear and unambiguous.

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

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

The description states when to use the tool (proactive monitoring) and includes prerequisites ('Requires a Pipeworx OAuth account'). It also explains supported subscription types with examples. However, it does not explicitly contrast with alternatives like 'recent_alerts' for pulling, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, covering safety and idempotency. The description adds behavioral context about returning example questions with tool+argument shapes, but doesn't add significant new behavioral traits beyond what annotations imply.

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 key phrases and common user intents. While slightly long, every sentence adds value—clarifying purpose, usage, and output. Could be tightened slightly but remains 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 tool's simplicity (no output schema, one optional param), the description is complete. It explains what the tool returns, when to use it, and how to invoke it properly. No gaps remain for the agent to understand its role.

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 single optional parameter described inline. The description adds important meaning: it clarifies the topic parameter focuses on specific categories (finance, pharma, etc.) and explains that omitting it yields a cross-category spread. This adds value beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions and positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists all tools).

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

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

Explicitly instructs to use this FIRST when unfamiliar with Pipeworx, or to learn meta-tool calls. Also notes that omitting topic gives full spread, and passing topic focuses on one area. Provides clear context for when-not-to-use and alternatives are implied.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation vs deletion, and historical event preservation. It complements the idempotentHint and non-destructive annotations well.

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 only two sentences, with the core action in the first sentence and key behavioral details in the second. Every sentence is informative and necessary.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, deactivation behavior, and historical data implications. It is complete and references relevant 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?

The input schema already provides a full description of the 'id' parameter (uuid from subscribe). The description does not add new parameter-specific meaning, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description provides clear context on who can use it (only own subscriptions) and the outcome (deactivation, not deletion, with historical events preserved via 'recent_alerts'). It does not explicitly state when not to use it, but the guidance is strong.

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

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

Annotations already indicate safe, idempotent behavior. Description adds substantial value: lists verdict types, extracted structured form, actual value with citation, and percent delta. Also discloses data source (SEC EDGAR + XBRL) and versioning.

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

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

Front-loaded with keywords and examples, followed by scope, output details, and comparison with alternatives. Every sentence serves a purpose; no wasted words.

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

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

Given simple schema and rich annotations, the description fully explains purpose, usage, output structure, and domain restrictions. Compensates for missing output schema by detailing return fields.

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

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

Schema coverage is 100% for single parameter 'claim'. Description reinforces with multiple examples and clarifies the natural-language format, adding context beyond the schema's brief description.

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

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

Description uses specific verbs like 'verify', 'fact check', and clearly states it handles natural-language claim verification against authoritative sources. It specifies the domain (company-financial claims) and distinguishes from siblings by noting it replaces multiple 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?

Explicitly says to use when checking factual correctness of user statements. Implies limitations to company-financial claims for public US companies, hinting at when not to use. Lacks direct alternative tool names among siblings.

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