Hubspot

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that the tool probes multiple models, returns scores, and that Anthropic calls are passed through to the user's own API key. 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 (two sentences plus return summary), well-structured, and front-loaded with the key action. Every sentence adds value.

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

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

Despite no output schema, the description specifies the return structure (per-model fields and combined view). Use cases are listed. It could mention pagination or limits but covers essentials for a straightforward probe tool.

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

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

Schema coverage is 100%, and the description adds meaningful context: entity examples, supported models, API key usage, and context for disambiguation. This goes beyond the schema, clarifying how to use each parameter.

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 visibility scores per model, with specific examples of use cases. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on scoring and multiple model probing.

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

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

The description provides context (AI-marketing audits, pre-launch checks, competitive monitoring) and mentions the default free model and BYO key for Anthropic. However, it does not explicitly state when not to use it or compare to alternatives like 'scan_competitor_ai_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?

No annotations are provided, so the description carries the full burden. It explains that the tool 'picks the right tool, fills the arguments, and returns the result', which gives insight into its autonomous behavior. However, it does not disclose limitations, such as potential latency, error handling, or whether it can access all data sources. No contradiction with missing 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: three sentences that front-load the purpose and include examples. Every sentence adds 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 the tool's simple interface (one string parameter) and no output schema, the description is largely complete. It explains the behavior of routing to the best data source and filling arguments. However, it could mention that results are returned as text or clarify that the tool does not support follow-up questions.

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 parameter 'question' described as 'Your question or request in natural language'. The description adds context by emphasizing plain English and providing examples, but the schema already adequately describes the parameter. 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's purpose: to answer natural language questions by selecting the best data source and filling arguments. It provides concrete examples like 'What is the US trade deficit with China?' that illustrate usage. This distinguishes it from sibling tools that are either tool-discovery (discover_tools) or specific CRM lookups (hs_get_company, etc.).

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

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

The description explicitly tells users to 'just describe what you need' without browsing tools or learning schemas, implying a high-level query interface. However, it does not explicitly state when not to use this tool (e.g., for direct, structured queries that siblings can handle). The examples help but lack 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 declare readOnlyHint=true and destructiveHint=false, and the description aligns by stating it 'pulls data', 'fans out to packs', and returns evidence. No contradictions; description adds details on classification and pack selection.

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 informative but slightly verbose; could trim examples like 'crypto+fred+gdelt'. However, it front-loads the core purpose and is structured logically.

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 what is returned (evidence packet + market-vs-model comparison). Covers inputs, process, and outputs comprehensively for a complex tool.

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

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

Schema coverage is 100%, but description adds significant meaning: explains that 'market' accepts slug, URL, or question text, and 'depth' distinguishes quick from thorough. Provides context 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 researches Polymarket bets by pulling Pipeworx data, with specific verb 'Research a Polymarket bet'. It distinguishes from sibling tools like ask_pipeworx by offering a consolidated, bet-specific research flow.

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...', 'is there edge...'. It also contrasts with 'agents that have to discover the packs themselves', showing when to prefer 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?

With no annotations provided, the description carries full transparency burden. It discloses the data sources (SEC EDGAR for company, FDA for drug) and that returns paired data with pipeworx:// URIs. It does not explicitly state read-only or mention rate limits, but the lack of side effects is reasonably inferred.

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 four sentences with no wasted words. It front-loads the core purpose, then efficiently details per-type output and the efficiency benefit. Every sentence serves a clear role.

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 two parameters and no output schema, the description adequately explains inputs and outputs. It mentions return format (paired data + URIs) and replaces many calls. It could mention result ordering or error cases, but the level of detail is sufficient for a comparison tool.

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

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

The input schema covers both parameters with descriptions, achieving 100% coverage. The description adds context by linking the 'type' parameter to specific data fields and explaining the 'values' format per type, adding value beyond the schema's enum and array descriptions.

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

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

The description clearly states 'Compare 2–5 entities side by side in one call' with specific data fields for each type (company vs drug). It distinguishes itself from sibling tools like single-entity getters by emphasizing batch comparison and listing the replaced sequential calls.

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

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

The description implies use when comparing multiple entities by stating it replaces 8–15 sequential calls. It does not explicitly exclude single-entity comparisons, but the sibling tools cover that. The guidance is clear but could be more explicit about when to use alternatives.

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

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

The description discloses key behavioral traits: it returns 'the most relevant tools with names and descriptions', and it is intended as a discovery step. No annotations are provided, so the description carries the full burden. It does not mention any side effects, permissions, or rate limits, but given the search-only nature, the behavioral transparency is adequate for an AI agent.

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 concise: three sentences that are front-loaded with the core purpose. Every sentence adds value: first sentence states the action, second explains the return, third gives 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 the tool's complexity (simple search with 2 parameters, no output schema), the description is complete. It explains what the tool does, how to use it, and when to call it. No missing details that would hinder an AI agent's decision 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?

The input schema has 100% coverage, with descriptions for both parameters (query and limit). The description adds value by explaining the usage of the query parameter (natural language description of what you want to do) and implicitly reinforces the limit's role. Since schema coverage is high, the baseline is 3, but the description provides an example query, raising the score to 4.

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

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

The description clearly states the tool's purpose: to search the Pipeworx tool catalog using a natural language query and return the most relevant tools. It specifies the verb 'search', the resource 'tool catalog', and the action 'describe what you need', which distinguishes it from sibling tools that perform different operations like asking questions, forgetting, remembering, or working with HS entities.

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

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

The description provides explicit guidance on when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This tells the agent the priority and context for invocation, effectively differentiating it from the other tools listed as 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?

No annotations provided, so description carries full burden. It discloses that it returns citation URIs and replaces 10-15 calls, but does not explicitly state read-only behavior, error handling, or performance characteristics. Basic transparency is present but could be more comprehensive.

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

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

Three efficient sentences, front-loaded with main purpose, no redundancy, and each sentence adds unique value (data sources, output format, efficiency gain, alternative tools).

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 what data is included for company type, output format, and provides alternatives for edge cases. Lacks details on error handling or response structure beyond URIs, but overall suffices for the tool's intended use.

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

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

Schema coverage is 100%, providing baseline 3. Description adds value by clarifying that the type parameter only supports 'company' and that the value parameter does not accept names, directing to resolve_entity instead.

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 a full profile across multiple packs, lists specific data sources (SEC, XBRL, patents, news, LEI), and distinguishes from sequential calls and the sibling usa_recipient_profile for federal contracts.

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

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

Explicitly tells when to use (full profile), when not to use (federal contracts should use usa_recipient_profile), and implies that for name-only inputs, resolve_entity should be used first.

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?

No annotations are provided, so the description must disclose behavior. It states the action (delete) and identifies the required parameter (key). However, it doesn't mention side effects (e.g., if memory is permanently removed) or any prerequisites like authorization. The description is adequate but lacks depth.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the action and resource. Perfect conciseness 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?

Given the tool is simple (1 parameter, no output schema, no annotations), the description is complete enough. It states the action and required input. No output schema means return value doesn't need 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 description coverage is 100%, so the input schema already describes the 'key' parameter as 'Memory key to delete'. The description simply says 'by key', adding minimal value. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Delete' and the resource 'stored memory by key'. It clearly distinguishes from sibling tools like 'recall' and 'remember' which imply retrieval and storage, not deletion.

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

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

The description implies usage when you want to delete a memory by key, but it doesn't explicitly state when not to use it or provide alternatives. The sibling tools include 'remember' (store) and 'recall' (retrieve), which offer some context, but no direct comparison.

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 nondestructive operation. Description adds that the tool fetches, extracts title/description/key links, and emits standard markdown format, which is consistent and informative.

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

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

Three sentences: first defines purpose, second outlines process, third lists use cases. No wasted words, information front-loaded. Highly concise and structured.

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

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

Given the low complexity (2 params, no output schema, no nested objects), the description is complete: covers purpose, process, behavior, and use cases. Annotations provide sufficient behavioral hints.

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

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

Schema coverage is 100% with clear descriptions for both 'url' and 'max_links'. Description does not add further parameter details beyond schema, 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?

Description clearly states the tool generates an llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on generation rather than scanning.

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

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

Explicitly lists three use cases: getting client sites indexed, drafting for own projects, or auditing AI crawler view of competitors. Lacks explicit when-not-to-use or alternatives, but context is clear enough.

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

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

Annotations are empty, so description must cover behavior. It only states it returns a single company by ID, but doesn't mention if it returns all fields, or any potential errors.

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

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

Single sentence, clear and concise. No unnecessary 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?

No output schema, and tool is simple with one parameter. The description is minimal but lacks details like response format or error conditions.

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

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

Schema description coverage is 100% with a clear parameter 'id'. The description does not add extra meaning beyond the schema.

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

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

The description clearly states the verb 'Get' and resource 'a single HubSpot company by ID'. It distinguishes from sibling tools like hs_list_companies which lists multiple companies.

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 vs other tools. For example, hs_list_companies or hs_search_contacts are alternatives but no comparison is given.

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 correctly identifies the tool as a read operation (get). With no annotations provided, the description carries full burden and is adequate but lacks additional context like rate limits, error cases, or required permissions.

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

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

The description is a single sentence, front-loaded with the verb 'Get', and contains no unnecessary words. It is maximally concise while conveying essential information.

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

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

Given the tool is simple (1 parameter, no output schema, no nested objects), the description is largely complete. It could be improved by noting the return format or potential errors, but it is sufficient for selecting and invoking 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?

The description does not add meaning beyond the input schema for the 'id' parameter. Since schema coverage is 100% (the schema documents the parameter), a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the resource ('HubSpot contact'), and the identifying mechanism ('by ID'). It distinguishes from sibling tools like hs_list_contacts and hs_search_contacts, which serve different purposes.

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

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

The description implies usage when you need a single contact by ID, but it does not explicitly state when to use this tool over alternatives like hs_search_contacts. No guidance on prerequisites or 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 states it gets a single deal by ID, which implies a read-only operation. Since annotations are empty, the description partially fulfills the transparency burden by indicating it is a retrieval action. However, it does not disclose any behavioral traits like potential errors (e.g., if ID not found), rate limits, or data freshness.

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, clear sentence that states the tool's purpose without unnecessary words. It is front-loaded and concise.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is adequate but not complete. It does not mention what the response contains or any edge cases. However, for a simple retrieval tool, a minimal description can suffice.

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

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

The input schema has 100% coverage, with one required parameter 'id' described as 'HubSpot deal ID'. The description adds no further semantic meaning beyond the schema. Per guidelines, with high schema coverage, baseline is 3.

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

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

The description clearly states the action (Get), the resource (a single HubSpot deal), and the identifier (by ID). It distinguishes from sibling tools like hs_list_deals (which returns multiple deals) and hs_get_company/hs_get_contact (which retrieve different entity types). However, it does not explicitly mention that the tool is for retrieval only, which is implied but not explicit.

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 is provided on when to use this tool versus alternatives. For example, it does not mention that hs_list_deals should be used to retrieve multiple deals or that hs_search_contacts is for searching. The agent would need to infer from sibling tool names.

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?

With no annotations, the description must disclose all behavioral traits. It mentions pagination via 'after' cursor and limit, but does not state if the tool is read-only (presumably it is), what happens on errors, or any rate limits. The lack of annotations increases the burden, and the description falls short.

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 and efficiently conveys the purpose and key feature (pagination). It is front-loaded and concise, though it could be slightly more structured.

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

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

Given the low complexity (2 optional params, no output schema, no nested objects), the description is adequate but not complete. It explains pagination but omits details like default limit, maximum, and the fact that 'after' comes from a previous response (implicit from schema). With sibling tools, more context on when to list vs search would help.

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

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

Schema description coverage is 100%, so the description adds no new parameter info. The description mentions 'pagination via limit and after cursor', which echoes the schema. Baseline of 3 is appropriate since schema already covers parameters.

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

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

The description clearly states the verb 'List' and resource 'companies from HubSpot CRM'. It also mentions pagination support, which adds specificity. However, it does not distinguish from sibling tools like hs_list_contacts or hs_list_deals, though the resource type is inherently 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 provides no guidance on when to use this tool versus alternatives, such as hs_get_company for a single company or hs_search_companies (which doesn't exist but is implied). No exclusions or prerequisites are mentioned.

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

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

Annotations are empty, so description must cover behavioral traits. Mentions pagination (limit, after), which is helpful. But does not disclose if contacts are sorted, or any potential rate limits or data freshness.

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, concise and front-loaded with purpose and key feature (pagination). 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 low complexity (2 params, no output schema), description is adequate but could mention return format or default sorting. Completeness is moderate.

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. Description does not add meaning beyond schema for parameters, but the schema itself is clear.

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

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

Clearly states it lists contacts from HubSpot CRM and mentions pagination support. However, it does not differentiate from sibling tools like hs_search_contacts, which also returns contacts but via 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?

No guidance on when to use this tool versus alternatives like hs_search_contacts for filtering or hs_get_contact for a single contact. Does not mention 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 adds behavioral context about pagination (limit and after cursor) beyond what annotations provide (none). However, it does not disclose default limit, maximum limit, or any side effects. Since annotations are empty, the description carries the burden, but it is adequate.

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: first states the core purpose, second adds key functionality. It is concise and front-loaded, but could be slightly more efficient by merging or adding a usage hint.

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 listing tool with good schema coverage and no output schema, the description is minimally complete. It explains pagination but does not mention default behavior or response structure. Adequate but not exceptional.

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

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

Schema description coverage is 100%, so the schema already describes both parameters clearly. The description only mentions pagination generically, adding no new semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists deals from HubSpot CRM and mentions pagination support, which is a key feature. It is distinct from sibling tools like hs_get_deal (single deal) and hs_list_contacts/hs_list_companies (different 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 implies usage for listing deals with pagination, but it does not explicitly state when to use this tool versus alternatives like searching or getting a single deal. No exclusions or prerequisites are mentioned.

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

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

No annotations are provided, so the description carries the burden. It indicates that matching is against name, email, and 'other default searchable properties,' which is somewhat vague but implies a search operation. No mention of rate limits, authentication, or side effects. Since it's a search tool, destructive behavior is unlikely, but the description could be more explicit about read-only nature.

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

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

The description is a single sentence that is clear and to the point. It front-loads the purpose and mentions key matching fields. No unnecessary words.

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

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

For a search tool with 2 parameters and no output schema, the description adequately explains what the tool does. However, it could mention pagination behavior (limit and offset) or that results are paginated. The lack of output schema means the description doesn't need to explain return values, but it could hint at the response structure.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds that the query matches against name, email, and other properties, which provides some context beyond the schema's generic 'Search query' description. However, it doesn't add details about the 'limit' parameter beyond what the schema says.

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

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

The description clearly states the tool searches HubSpot contacts by a query string and matches against default properties like name and email. It distinguishes itself from sibling tools like hs_get_contact (which likely retrieves a single contact) and hs_list_contacts (which probably lists all 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. For example, when to use search vs. list vs. get is not mentioned. No exclusion criteria or prerequisites are provided.

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?

No annotations are provided, so the description carries the full burden. It discloses the rate limit (5 messages per identifier per day) and the constraint to not include end-user prompts. For a non-destructive feedback tool, this is sufficient.

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 concise with three sentences covering purpose, usage guidelines, and rate limit. Every sentence adds value without redundancy.

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

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

Given the tool is a simple feedback submission with no output schema, the description adequately covers what to use it for, how to format feedback, and constraints. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, but the description adds value by explaining the enum values for 'type' and giving guidance on the 'message' field (be specific, 1-2 sentences, 2000 chars max). The optional context object is also explained.

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 sends feedback to the Pipeworx team and lists specific use cases (bug reports, feature requests, etc.), differentiating it from sibling tools that are data retrieval or memory focused.

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

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

It explicitly tells when to use the tool (for various feedback types) and what not to include (end-user prompt verbatim). Mentions rate limit. However, it does not specify when not to use or provide alternatives.

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

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

Annotations already indicate safe, read-only behavior; description adds caching details, data source, and privacy assurances, going beyond what annotations provide.

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

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

Concise yet comprehensive, with bullet points for use cases and no wasted sentences.

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?

While output schema is absent, description states what is returned (tools, packs, volume). Could clarify format, but sufficient for its purpose.

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 enum description; description adds nuance about window trade-offs, slightly elevating above baseline.

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

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

The description clearly states it returns trending tools, packs, and call volume, and it distinguishes itself from siblings like discover_tools by focusing on aggregated usage signal.

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

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

Three explicit use cases are provided, but no when-not-to-use or alternative tools are mentioned; however, the clarity of use cases earns a 4.

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

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

Annotations (readOnlyHint, openWorldHint, destructiveHint) are consistent with the description. The description adds useful behavioral details about monotonicity checking and cross-event search, enhancing transparency beyond annotations.

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

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

The description is relatively concise but slightly verbose with inline bullet points. It front-loads the core purpose but could be tighten 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 two-mode complexity and lack of output schema, the description adequately covers usage modes and return types ('ranked opportunities with suggested trade direction + reasoning'). It is mostly complete for agent decision-making.

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

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

Schema coverage is 100%, and the description adds meaning by explaining how each parameter is used (e.g., 'event slug or full URL', 'topic or seed question') with examples, providing extra context 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 finds arbitrage opportunities via monotonicity violations and specifies two distinct modes ('event' and 'topic') with concrete examples. It differentiates itself from sibling tools by focusing on Polymarket arbitrage.

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 each mode (single-event vs cross-event) with a real-world example. It does not explicitly state when NOT to use the tool, but the guidance is clear and practical.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds significant behavioral detail: the lognormal model, grouped asset processing, single price history fetch, edge computation, and ranking logic. No contradictions.

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

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

The description is a single coherent paragraph of about 5-6 sentences. It efficiently conveys the algorithm and purpose without unnecessary redundancy. Slight improvement could be splitting for readability, but it remains 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 lacking an output schema, the description mentions the return format (top N ranked by edge magnitude with suggested trade direction). It also explains the underlying logic (FRED model, coinpaprika price). For a discovery tool, this is sufficient, though more explicit output field details could help.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description does not add new meaning beyond the schema's parameter descriptions, which already specify defaults, max values, and enum options. It provides general context but no additional parameter semantics.

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

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

The description clearly states the action (scan and return), the resource (highest-volume Polymarket markets where Pipeworx data disagrees), and the specific function (using a lognormal model from FRED and live coinpaprika price). It distinguishes itself from siblings like polymarket_arbitrage by focusing on model-based discrepancy detection.

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 it's built for the 'what should I bet on today' question, helping agents discover opportunities without manual paging. While it does not list exclusions or alternative tools, the context is clear enough for an agent to know when to invoke 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 mark the tool as read-only and idempotent. The description adds valuable context about the return format (leg-by-leg prices and spreads) and the fact that it fetches matching events across venues, which is beyond what annotations convey.

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, return format). It is slightly verbose but every sentence adds value. Could be slightly more concise, 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?

There is no output schema, so the description fully explains the return values: leg-by-leg prices as probabilities and spreads in percentage points. It also explains the rationale for the tool, making it self-contained.

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

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

100% schema coverage ensures all three parameters are described. The description adds significant meaning by explaining the two modes, listing example topic values, and providing format examples for tickers and slugs.

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 computes a cross-venue spread between Kalshi and Polymarket, with explicit mention of the arb signal. It distinguishes from sibling tools like polymarket_arbitrage by focusing on two modes (topic vs explicit tickers) and the specific spread calculation.

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 explains when to use each mode: topic for pre-mapped shortcuts, explicit tickers for custom pairings. It implies usage for arbitrage detection but does not explicitly mention when not to use it or direct 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?

With no annotations, description carries the burden. Describes behavior (list vs retrieve) but does not mention side effects, authorization, or return format beyond 'memory' concept. Adequate but could be richer.

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

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

Two sentences, front-loaded with purpose, efficient and clear.

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 one optional parameter, no output schema. Description is sufficient for a straightforward retrieval tool, covering both retrieval modes.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds context about 'omit to list all keys' but does not add more detail beyond schema.

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

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

Clearly states the tool retrieves memories by key or lists all if key omitted, distinguishing it from sibling tools like 'remember' (store) and 'forget' (delete).

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

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

Explicitly says to use for retrieving context saved earlier, implying when to use (for recall). Lacks explicit alternatives or when-not-to-use, but sibling names and context provide 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?

With no annotations, the description fully discloses key behaviors: parallel fan-out to multiple sources, accepted 'since' formats with examples, return structure (changes, count, URIs), and that 'type' supports only 'company'. 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 (3 sentences) yet packed with essential information. It is well-structured, front-loading the purpose and then detailing behavior and usage.

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

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

Despite no output schema, the description explains the return format (structured changes, total_changes count, pipeworx:// URIs) and parallel fan-out. With full parameter coverage and clear usage guidance, it is complete for agent use.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema: it explains 'since' can be ISO or relative, gives examples, suggests typical usage ('30d' or '1m'), and clarifies that 'type' is currently limited to 'company'.

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: 'What's new about an entity since a given point in time.' It distinguishes itself from siblings like entity_profile by focusing on changes, not full profiles, and mentions fan-out to multiple sources.

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 to use for 'brief me on what happened with X' or change-monitoring workflows, providing clear usage context. It does not explicitly state when not to use, but implies differentiation from sibling tools like entity_profile and ask_pipeworx.

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?

No annotations are provided, so the description carries the full burden. It discloses persistence behavior ('Authenticated users get persistent memory; anonymous sessions last 24 hours'), which is crucial for an agent. No contradiction with annotations exists.

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

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

Three sentences, each adding value: action, use case, persistence distinction. No filler, front-loaded with purpose.

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

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

Given the simple input schema (2 required string params), no output schema, and no annotations, the description is complete. It covers purpose, usage, and behavioral nuance (persistence). Sibling tools like 'recall' and 'forget' complement it.

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 already describes both parameters well. The description adds minimal extra meaning beyond what the schema provides (e.g., examples in value description). 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's function: 'Store a key-value pair in your session memory.' It specifies the resource (session memory) and the action (store), distinguishing it from siblings 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 context: 'Use this to save intermediate findings, user preferences, or context across tool calls.' It also differentiates between authenticated (persistent) and anonymous (24-hour) sessions, but does not explicitly mention when not to use it or 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?

With no annotations, the description fully bears the burden. It discloses versioning (v1), accepted input formats, and output fields (ticker, CIK, company name, pipeworx URIs). It reasonably implies read-only behavior but could mention idempotency or side effects.

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

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

Two sentences with no redundancy. First sentence states purpose and scope; second provides version, examples, return values, and efficiency claim. Every sentence adds value.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers all needed: input formats, output fields, and efficiency benefit. 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 concrete examples (AAPL, 0000320193, Apple) and explains that value can be ticker, CIK, or name, enriching the schema's meaning.

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

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

The description clearly states the action ('resolve an entity to canonical IDs') and the resource ('across Pipeworx data sources'). It distinguishes from sibling tools by specifying that it replaces 2–3 lookup calls and focuses on Pipeworx data, unlike the hs_* tools for HubSpot.

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 guidance on when to use (when you need canonical IDs for a company) with examples of inputs (ticker, CIK, name). It mentions efficiency (replaces multiple calls) but does not explicitly exclude alternative tools or scenarios.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, returns a ranked list with score, confidence, and signal density, complementing the annotation information.

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 exceptionally concise with two sentences that front-load the key purpose and immediately follow with a usage example. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description details the output: 'ranked list with score, confidence, signal density per entity.' It covers purpose, usage, parameters, behavior, and output, making it complete for effective tool selection and invocation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaning beyond the schema, such as 'First entry treated as the subject for narrative; rest are competitors' and clarifies the role of _apiKey and models, increasing the agent's understanding.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side,' specifying the action (compare) and the resource (AI visibility). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by mentioning probing with ai_visibility_check and ranking.

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

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

Provides a concrete use case: 'competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies use over single-entity checks, but does not explicitly state when not to use or mention alternatives beyond the sibling list.

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

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

No annotations provided, so description fully carries the burden. Discloses behavior: returns verdict, extracted structured form, actual value with citation, percent delta. Also mentions underlying data sources (SEC EDGAR + XBRL). No contradictions.

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

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

Three sentences, front-loaded with main action, 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?

Given single parameter, no output schema, and no nested objects, description is complete. Explains purpose, domain, return values, and efficiency benefit.

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 'claim' with schema description coverage of 100%. Description adds example values and clarifies it's natural-language, adding value beyond the schema.

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

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

Clearly states the tool fact-checks natural-language claims against authoritative sources, specifies the domain (company-financial, US public companies), and lists return values. Distinguishes from siblings by noting it replaces 4–6 sequential agent 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 when to use: for factual claims, especially financial ones. Implicitly limits to v1 and US public companies, but does not explicitly state when not to use or provide alternative tools.

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