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

Discloses key behavioral traits: deletes relationship link, does not delete objects, uses v4 API. No annotations provided, so description bears full burden; could add info on irreversibility or required permissions, but current content is clear and 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?

Two concise sentences, front-loaded with action and result. No redundant words; every sentence earn its place by stating purpose and providing alternative.

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 essential aspects: purpose, effect, and alternative. No output schema needed. Missing minor details like reversibility or required scopes, but overall complete for a simple delete operation.

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 meaningful parameter information beyond schema; it rephrases source/target but adds no new details.

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

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

Explicitly states it removes all associations between two HubSpot CRM objects using v4 API and clarifies it does not delete the objects themselves. Distinguishes from sibling by mentioning the batch archive endpoint for removing specific labeled associations.

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 this tool (remove all associations) and when not (for specific labeled associations, use batch archive). Clearly directs to alternative endpoint.

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?

Provides max pairs and default type IDs but lacks details on error handling, idempotency, partial failures, or auth requirements. No annotations to supplement.

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 paragraphs, front-loaded with key info. Could be slightly tighter but overall efficient.

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

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

Covers input structure, defaults, and examples but misses return value description and error handling. For a batch tool with no output schema, these omissions are notable.

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 schema already describes parameters. Description adds default type IDs mapping, which is helpful but not essential. 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?

Clearly states it batch-creates associations between HubSpot object pairs, distinguishes from individual creates via 'more efficient than individual creates', and provides specific use case 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 says when to use (e.g., after bulk import, linking multiple deals) and notes maximum 100 pairs, but does not explicitly say when not to use (e.g., single associations should use individual create).

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 full burden of behavioral disclosure. It states 'Create or update' suggesting idempotency, but does not confirm if update means overwriting existing associations or adding new ones. It also does not mention permissions (e.g., required scopes), error handling (e.g., what happens on conflict), or rate limiting. These gaps reduce 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?

The description is front-loaded with purpose, then provides a helpful reference table for default typeIds. However, the table is somewhat lengthy and could be streamlined or moved to a usage note. The description is concise enough but not optimally structured; it mixes general usage with specific examples.

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

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

Given the tool has 5 required parameters, no output schema, and sibling tools, the description covers key usage examples but lacks return value explanation (e.g., the created association ID or confirmation). It also does not mention that associations can be one-to-many or that the 'associationCategory' field limits the category. For a creation tool, information about the response (e.g., status, association URI) is important for the agent to know what to expect.

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

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

Input schema has 100% coverage with descriptions for each parameter, so baseline is 3. The description adds limited value beyond schema: it provides a table of default HUBSPOT_DEFINED typeIds for common object pairings, which aids quick use but not essential. No parameters are explained in more depth than 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 creates or updates an association between two HubSpot CRM objects using the v4 API, and lists example link combinations (call to contact, etc.). It is specific about the resource and action. However, it does not explicitly differentiate from sibling tools like hubspot_associations_batch_create, though the singular 'create' implies single pair. Purpose is clear but could be stronger by contrasting with batch operation.

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 versus alternatives (e.g., batch_create for multiple associations, archive to remove). The description implies direct use for single associations but does not state prerequisites, when not to use (e.g., if object types are invalid), or that associationTypes must be discovered via labels_list. Usage context is implied but not systematically addressed.

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 carries full burden. It correctly indicates a read operation and mentions runtime variability of typeIds, but does not describe the output format, pagination, or any prerequisites beyond parameters.

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 paragraphs: one for purpose, one for usage and example. Every sentence adds value with no redundancy or unnecessary detail.

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 two parameters and no output schema, the description covers the key aspects: purpose, usage context, an example, and a runtime warning. It could mention the return structure explicitly, but overall it is complete enough.

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 adequate parameter descriptions. The description adds value through an example mapping parameters to actual values, but does not provide significant additional semantic detail beyond the schema.

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

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

The description clearly states the action ('List'), the resource ('all available association label types'), and the scope ('between two HubSpot object types'), with an example that distinguishes it from sibling tools like hubspot_associations_create or hubspot_associations_list.

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 using this tool 'BEFORE creating associations' and warns against hardcoding typeIds due to portal differences. While it doesn't explicitly list when not to use it, the guidance is strong and contextually relevant.

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 behaviors. It mentions pagination and the return format but lacks details on rate limits, authentication, or error handling. It is adequate but could be more transparent.

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

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

The description is two sentences, front-loading the purpose and providing a concise return format. 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 list tool with 5 parameters and no output schema, the description covers the essential use case and pagination. It could mention error or empty results, but it's sufficient for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the pagination cursor usage and giving example values for fromType/toType, which goes beyond the schema's generic 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 lists associated records for a HubSpot object, giving specific examples like contacts with a deal. It uses a specific verb 'List' and resource 'associated records', and distinguishes from sibling tools like create or archive.

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 retrieve associations) and how to paginate. However, it does not explicitly state when not to use it or mention alternative tools, though siblings are listed.

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 must fully disclose behavior. It effectively explains the effects of each hs_execution_state value (continue, continue despite failure, stop enrollment). It does not cover authentication, rate limits, or idempotency, but for a simple callback completion this 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?

Three short, well-front-loaded sentences: purpose, timing, and execution state options. Every sentence earns its place with no redundancy or 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?

Given two parameters (one nested) and no output schema, the description covers the essential purpose and behavior. It could mention that no output is returned or that the workflow continues based on the state, but it is sufficiently complete for this tool's complexity.

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

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

The schema already describes both parameters. The description adds value by explaining the practical meaning of the hs_execution_state enum values (SUCCESS continues, FAIL_CONTINUE continues despite failure, BLOCK stops enrollment). This goes 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?

The description clearly identifies the verb 'complete' and resource 'async custom-action callback' within HubSpot Workflows. It specifies the version (v4 automation runtime). However, it does not explicitly differentiate this single-callback tool from its batch counterpart among siblings, reducing clarity of 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 states when to call ('after your external action finishes') and explains the three possible states. However, it provides no guidance on when not to use this tool, no mention of prerequisites (e.g., having a valid callbackId), and no comparison with the sibling batch tool for multiple callbacks.

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?

Without annotations, description carries full burden. Mentions completion of callbacks but does not disclose side effects, idempotency, error handling, or permissions. Moderate 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?

Two sentences, front-loaded with main action, no extraneous words. Efficient structure.

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?

Lacks output schema; description does not specify return value or success/failure behavior. Adequate for a batch completion tool but incomplete regarding results.

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

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

Schema coverage is 100%; description restates schema constraints (each item needs callbackId and hs_execution_state) without adding new meaning beyond the schema. Baseline score.

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 verb 'complete', resource 'async custom-action callbacks', and specifies 'in bulk'. Distinguishes from singleton sibling 'hubspot_automation_callback_complete'.

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 case ('when your external system processed several workflow enrollments concurrently') and notes input structure requirements. Lacks explicit exclusions but 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?

The description fully discloses behavioral traits: it's a soft-delete (not permanent), records can be retrieved with archived=true, returns HTTP 204 on success, and provides alternative for permanent deletion. Since no annotations are provided, the description carries the full burden and excels.

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 action, second explains behavior and retrieval, third gives response and alternative. Front-loaded with 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?

For a simple 2-parameter tool with no output schema, the description covers all essential aspects: action, behavior (soft-delete vs permanent), retrieval method, response format, and alternative. 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 description coverage is 100%, so the baseline is 3. The description adds that it applies to 'all object types,' which is already implied by the enum in the schema. No significant additional semantic 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 'Archive (soft-delete) a HubSpot CRM record', identifying the verb (archive/soft-delete) and resource (CRM record). It distinguishes from siblings like batch_archive by implying single-record operation, and contrasts with permanent 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 explicitly mentions it applies to all object types and provides an alternative for permanent deletion ('To permanently delete, use the HubSpot UI or the GDPR delete endpoint'). It implicitly guides when to use this tool for reversible soft-delete, but does not explicitly differentiate from batch archive or other sibling tools beyond name.

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?

Without annotations, the description carries full burden. It discloses soft-delete behavior, retrievability with archived=true, empty response on success (HTTP 204), and the max inputs limit. This is sufficient for safe usage.

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 extra words. Front-loads key information (archive, soft-delete, batch) and packs behavioral notes concisely.

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 and no annotations, the description covers the essential behavioral aspects. Could mention access requirements, but not critical for basic usage.

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

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

Schema coverage is 100%, so the description adds minimal value beyond schema. It reiterates the limit and ID requirement, but does not provide additional context or constraints.

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 archives (soft-deletes) up to 100 HubSpot CRM records in a single request, applies to all object types. This distinguishes it from single-record archive (hubspot_crm_archive) and other batch operations like batch_create or batch_read.

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 mentions the batch size limit (1–100) and that it works for all object types. Does not provide when-not-to-use or alternative tools, but the context of sibling tools implies proper usage.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the 100-record limit, per-record error returns, optional associations, and the hs_timestamp requirement for engagements. However, it does not specify whether the batch operation is fully atomic or handles partial failures, which would be useful for a mutation tool. This gap prevents a 5.

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, each earning its place: 1) core purpose and batch size, 2) applicability and input structure, 3) special requirement for engagements, 4) return behavior. No fluff, well-front-loaded.

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

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

Given the tool's complexity (batch creation with optional associations), no output schema, and no annotations, the description covers the key aspects: limit, input format, special requirement, and return type. It could be more explicit about output structure (e.g., whether IDs are returned) but is still quite complete for a batch creation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by highlighting the batch limit, the engagement timestamp requirement, and the atomic creation of associations. This additional context justifies 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 the tool creates up to 100 HubSpot CRM records in a single request, applicable to all object types. It distinguishes from siblings like hubspot_crm_create (single record) and other batch operations (read, update, upsert, archive) by specifying batch creation and the 100-record limit.

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 usage context: it's for creating records in bulk, applies to all object types, and notes a special requirement for engagements (hs_timestamp). While it doesn't explicitly contrast with alternatives, the sibling tools list and the description's focus on batch creation make the usage clear. A score of 4 is appropriate due to lack of explicit 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 discloses key behaviors: it reads records (implied read-only), handles per-record errors, and supports custom idProperty. It does not mention authentication, rate limits, or side effects, but since no annotations are provided, it carries the full burden and does well for a read operation.

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 at 5 sentences, front-loaded with the main purpose, and each sentence adds value (limit, object types, properties, idProperty, response structure). No redundancy or fluff.

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

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

For a batch read tool without an output schema, the description adequately covers inputs, limits, error handling, and response structure. It explains the core functionality and edge cases (custom idProperty) 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?

The input schema already provides clear descriptions for all 5 parameters (100% coverage). The description adds context by explaining how to use idProperty and that properties must be specified to control fields, but does not provide significant new meaning beyond the schema.

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

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

The description clearly states it reads up to 100 HubSpot CRM records by ID in a single request, applicable to all object types. The verb 'Read' and resource 'HubSpot CRM records' are specific, and the batch nature distinguishes it from sibling tools like hubspot_crm_get (single record) or hubspot_crm_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?

The description provides guidance on specifying properties and using idProperty for custom lookups, and mentions the 100-record limit. However, it does not explicitly state when to avoid this tool or contrast it with alternatives like search or list for filtering instead of IDs.

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 carries the full burden. It discloses partial update behavior, property clearing via empty string, return format (batch response with errors), and the 100-input limit. It does not cover authentication or rate limits, but covers essential behavioral traits adequately.

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, with the main purpose stated first, followed by specific behaviors and limits. Every sentence adds necessary 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?

Given the tool has 2 parameters and no output schema, the description covers key aspects: operation type, batch size limit, partial update, property clearing, and return format. It is complete enough for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so parameters are well-documented in schema. The description adds value by explaining partial update, property clearing, and the requirement for hs_timestamp on engagements, which goes beyond the schema's property 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 updates existing HubSpot CRM records in batch, differentiating from siblings like batch_create and batch_upsert by specifying 'update' and 'partial update'. It also specifies the resource type and includes the batch limit.

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 indicates usage for batch updates, but does not explicitly mention when not to use it or alternative tools like single update (hubspot_crm_update). However, the batch context is clear, and the description includes the limit of 100 inputs.

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

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

Describes create/update behavior, input requirements, and idProperty uniqueness constraint. No annotations provided, so description does the heavy lifting; however, lacks details on partial failures, rate limits, or atomicity.

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 and front-loaded. Each sentence provides essential 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?

Covers primary aspects: action, required fields, limit, and special notes (unique property, timestamp). Missing error handling or response details, but overall adequate for a batch upsert 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 description adds extra context: idProperty must be unique, properties are string-only, and for engagements hs_timestamp is required. Adds value beyond schema.

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

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

Description clearly states 'Upsert up to 100 HubSpot CRM records' with the create/update logic, specifying the resource, action, and limit. Distinct from siblings like batch_create and batch_update.

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?

Specifies required inputs (idProperty, id, properties) and the 100-record limit. Notes that idProperty must be unique. Does not explicitly contrast with batch_create or batch_update, but the upselt nature is 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?

Annotations are absent, so the description must carry full burden. It mentions creation, return of the created record with id, and required properties per type. However, it omits error scenarios, permissions, or side effects like idempotency.

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

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

The description is three sentences, front-loaded with the core action, and efficiently covers required property variations and the associations option 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 no output schema and no annotations, the description adequately covers the tool's purpose, parameter requirements, and return value. It could be improved by mentioning error handling or limitations, but it is sufficient for basic 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?

The input schema already covers all parameters (100% coverage). The description adds value by highlighting the benefit of the `associations` parameter to avoid extra API calls, though it does not introduce new semantic details beyond the schema.

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

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

The description clearly states it creates a new HubSpot CRM record and lists all supported object types. It distinguishes itself from sibling CRUD tools (e.g., batch create, update, get) by focusing on single-record creation and inline associations.

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 on when to use the `associations` parameter to avoid separate API calls, but does not explicitly contrast with batch creation or other alternatives. It implies single-record creation but lacks 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?

Without annotations, description reveals key behaviors: returns 404 if missing or archived, properties parameter required for custom fields, archived parameter toggles record type. Good coverage but does not explicitly state 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?

Two sentences plus an emphasized note. Front-loaded with purpose, then key usage tips. No extraneous information. 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?

Covers purpose, all object types, required parameters, important optional parameter, error handling. Lacks response format description and usage of `associations` but overall adequate for a simple get tool with no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds value by emphasizing `properties` with example and explaining default behavior. Also clarifies `archived` and 404 implications. Does not add much for `associations` but overall enhances 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?

Explicitly states 'Retrieve a single HubSpot CRM record by its ID' and 'Works with all object types'. Clearly distinguishes from sibling tools like list, search, and batch read by specifying single record retrieval.

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 important guidance: always specify `properties` for non-default values and use `archived=true` for archived records. Mentions 404 error behavior. Does not explicitly compare to alternatives but 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?

No annotations are provided, so the description carries full burden. It discloses the paginated response shape and the behavior that only default properties are returned unless specified. It does not mention rate limits, authentication needs, or any side effects, but for a read-only list operation, the disclosed info 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 concise: two sentences and an important note. Everything is front-loaded with purpose and key behavior. 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 no output schema, the description explains the return shape and pagination mechanism. It covers all key aspects: supported object types, properties default, archived flag. It does not mention error responses or edge cases, but for a list tool, this is sufficient. The complexity (6 params, 1 required) is well-addressed.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining how to use the `properties` parameter (e.g., 'dealname,amount,closedate') and how pagination works with `pagination.nextCursor`. This context helps the agent correctly construct requests 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 lists HubSpot CRM records for multiple object types, with specific verb 'list' and resource 'CRM records'. It lists all supported object types and mentions pagination shape. However, it does not explicitly differentiate from sibling tools like hubspot_crm_search, which might be used for filtered 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 includes important usage notes about default properties and pagination, which guide correct invocation. However, it lacks explicit guidance on when to use this tool versus alternatives (e.g., search for filtering, get for single record) and does not 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?

No annotations are provided, so the description carries the full burden. It discloses rate limits, indexing latency, max results, and property requirements. However, it does not mention error behavior or response format, which would be helpful for a complete behavioral picture.

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: a clear lead sentence followed by bullet-pointed important notes. Every sentence adds value, 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?

Given the tool's complexity (search with filtering, sorting, paging) and no output schema, the description covers essential behaviors like rate limits, latency, max results, and property specification. It could be improved by explicitly stating the response format (list of records), but overall it is complete enough for an AI agent to use correctly.

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

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

All 7 parameters have schema descriptions (100% coverage), so baseline is 3. The tool description adds context about filter group structure and usage (e.g., OR-ed groups, AND-ed filters, max counts) but does not add significant new semantics per parameter beyond what the schema already 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 it searches HubSpot CRM records with filters, sorts, and full-text query, and applies to all object types. It distinguishes itself from sibling tools like hubspot_crm_get by explicitly recommending that tool for read-after-write.

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

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

The description provides explicit usage guidelines including rate limits (~5 req/s), indexing latency (do not use after create/update), max results (10,000), and the need to specify properties. It also recommends an alternative tool (hubspot_crm_get) for read-after-write 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?

With no annotations, the description discloses key behavioral traits: partial update, leaving omitted properties unchanged, clearing with empty string, and returning the updated record. It does not cover error conditions or permissions but is transparent enough for a standard update operation.

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, front-loaded with the core purpose, and each sentence adds necessary detail without redundancy or 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?

The description covers core usage, partial update semantics, and return value. However, since there is no output schema, it could be more specific about the response structure, but it is sufficient for an update tool with 3 well-described 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%, so baseline is 3, but the description adds value beyond the schema by explaining how to clear properties and noting that hs_timestamp is required for engagement objects, which aids correct parameter 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?

The description clearly states 'Update an existing HubSpot CRM record (partial update)' with a specific verb and resource, and distinguishes from sibling tools like hubspot_crm_create or hubspot_crm_get by emphasizing the partial update nature and applicability to all object types.

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 guidelines on how to use the tool (partial update, clearing properties) but does not explicitly state when to use this tool versus alternatives like batch update or upsert, leaving the agent to infer usage context.

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

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

With no annotations, the description fully carries the behavioral burden. It details the irreversible nature, association movement, property precedence (primary wins), and required OAuth scopes. This exceeds basic disclosure, though rate limits or error states are not mentioned.

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

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

The description is five sentences, front-loaded with the core purpose. Every sentence adds value (behavior, scopes, irreversibility). No redundant content, though minor tightening could improve conciseness.

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 (merge with 2 params, no output schema, no nested objects), the description covers all necessary context: what happens to associations, property conflict resolution, archival, irreversibility, and required scopes. An agent has sufficient information to use 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 coverage is 100% with clear parameter descriptions. The description adds emphasis on 'SURVIVING' and 'ABSORB' roles, reinforcing the schema but providing marginal extra value beyond it. 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 tool merges two deal records, specifying the primary and secondary roles and exactly what happens (associations moved, properties merged, secondary archived). It distinctively identifies this as a merge operation among sibling tools like hubspot_crm_archive or hubspot_crm_update.

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 when to use (when merging deals) but does not explicitly state when not to use or compare with alternatives like updating individually. It provides context on irreversibility and required scopes, but lacks explicit exclusions 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?

With no annotations provided, the description carries the full burden. It discloses the basic behavior (enrollment) and a prerequisite, but does not mention side effects, idempotency, error cases, or return values. It is adequate but not detailed.

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 (26 words), front-loaded with the main action, and contains no unnecessary 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?

For a simple mutation tool with fully described parameters, the description covers the primary action, prerequisites, and input hints. It does not describe output, but given no output schema, this is acceptable. The tool fits well among siblings.

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 restates the required parameters ('workflow's numeric ID and contact's email') but adds no new constraints or formatting beyond the schema, thus meeting but not exceeding the 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 the verb 'Enroll' and the resource 'a contact into a HubSpot Workflow (Automation v2)'. It distinguishes from siblings like hubspot_enrollment_unenroll by specifying the action direction, and includes prerequisites and input hints.

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 context by stating the prerequisite 'The contact must exist in HubSpot'. It does not explicitly mention when not to use or compare to alternatives like hubspot_enrollment_unenroll, but the context is clear enough for a simple action 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?

No annotations are provided, so the description must carry the full burden. It states the tool returns a list of workflows the contact is currently enrolled in, but does not disclose any behavioral traits such as side effects, rate limits, or permission requirements. For a read operation, this is minimal but acceptable.

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 long, front-loads the action and resource, and contains no redundant information. Every word 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 simple structure (single required parameter, no output schema), the description adequately explains what the tool does and returns. It could mention that results are limited to active enrollments, but it already says 'active'. Minor improvement possible but overall complete for its complexity.

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

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

There is one parameter (vid) with 100% schema description coverage. The tool description adds 'HubSpot VID (contact record ID)' which matches the schema's description. Since the schema already documents the parameter, the description adds no extra value beyond confirming the context.

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 ('Get') and resource ('active workflow enrollments for a contact by HubSpot VID'), clearly distinguishing it from siblings like hubspot_enrollment_enroll (enroll) and hubspot_workflows_list (list all workflows). It precisely states the action and the 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 clearly indicates when to use the tool (to retrieve enrollments for a specific contact). It does not provide explicit when-not-to-use or alternatives, but the context is clear enough given the sibling tools that perform different enrollment actions.

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 carries full burden. It explains the effect ('stops contact from progressing') but does not clarify if the contact is completely removed from the workflow or if the action is reversible. Nonetheless, it gives a clear behavioral summary.

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 the primary action. No extraneous information; every word serves a 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 no output schema and no annotations, the description is reasonably complete for a simple tool with two parameters. It could mention that the contact must be currently enrolled, but overall it provides sufficient context.

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

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

Schema description coverage is 100% for the two parameters. The description adds no additional meaning beyond what is already in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Unenroll a contact'), the resource ('HubSpot Workflow (Automation v2)'), and the effect ('stops the contact from progressing through remaining workflow actions'). This distinguishes it from sibling tools like hubspot_enrollment_enroll.

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 versus alternatives, nor prerequisites like the contact needing to be currently enrolled. The context of sibling tools provides some implicit differentiation, but the description lacks explicit when-to or 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?

No annotations provided. The description discloses important behaviors: naming constraints (lowercase underscores) and that name is immutable after creation. It lists common type/fieldType combinations.

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

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

The description is concise with a main sentence, a helpful table of common combinations, and a key note, all front-loaded 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 12 parameters (6 required) and no output schema, the description covers the creation intent, parameter combinations, and naming rules. However, it could mention return value 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 coverage is 100% with descriptions for all 12 parameters. The description adds value beyond the schema by explaining common type+fieldType combinations and naming convention.

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 creates a new custom property on a HubSpot CRM object type, and distinguishes from siblings like hubspot_properties_get/list by specifying the create action.

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 this to extend deal, contact, company, or other object records' which indicates when to use, but doesn't explicitly state when not to use or suggest 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 the tool's read-only behavior by stating it 'retrieves' data, but lacks explicit mention of error handling (e.g., if the property does not exist) or potential rate limits. Since no annotations are provided, the description carries full burden for behavioral transparency, yet it only minimally covers it.

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 brief (two sentences) and front-loaded with the core action and purpose. Every sentence provides essential information without unnecessary words, making it highly efficient.

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

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

The description adequately explains what the tool returns given no output schema, covering key details of the property definition. It does not mention edge cases like missing properties or pagination (not relevant), but for a simple retrieval tool, it is sufficiently complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by explaining that propertyName is the internal name and that the returned object includes type, field type, group, options, and default/custom status, which goes beyond the schema's parameter 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 specifies retrieving the full definition of a specific HubSpot CRM property by its internal name, including details like type, field type, group, options, and whether it's a HubSpot default or custom property. It effectively distinguishes this tool from siblings like hubspot_properties_list (which lists all properties) and hubspot_crm_get (which gets a record value).

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 advises that the tool is 'useful for inspecting field constraints before creating or updating records,' providing implicit guidance on when to use it. However, it does not explicitly state when not to use it or name alternative tools for different purposes, leaving room for clearer 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?

No annotations are provided, so the description carries the full burden. It explains what is returned (default and custom properties) but omits details about pagination, rate limits, or safety guarantees. A 3 is appropriate as it adds some context beyond a bare listing.

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 concise paragraph with the main purpose upfront. Every sentence adds value: the first states the main function, the second explains usage context, and the third lists types. No redundant text.

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

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

For a list operation with two parameters and no output schema, the description adequately covers what the tool does and what it returns. It mentions both default and custom properties, which is sufficient for an agent to understand the output.

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 description adds minimal value beyond the schema; it reiterates object type options without adding new semantic details.

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

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

The description starts with a clear verb-resource pair ('List all properties') and specifies the scope ('for a HubSpot CRM object type'). It distinguishes itself from sibling tools like hubspot_properties_create and hubspot_properties_get 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?

The description explicitly states the purpose ('discover available property names before reading or writing record data') and lists supported object types. However, it does not provide explicit when-not-to-use guidance or compare to sibling tools like hubspot_crm_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 carries full burden. It discloses that the tool is a helper that performs a single operation with inline associations, default association type IDs, and overrides. It does not explicitly mention idempotency, error behavior, or return value, but covers essential behavioral aspects 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?

Approximately 4-5 sentences, front-loaded with main purpose, then prerequisites, then details. No redundant information. Every sentence contributes to clarity and is well-structured.

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

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

Given the complexity (17 parameters, 3 required, nested objects, no output schema), the description covers prerequisites, association details, and scopes. It lacks explicit mention of return values or behavior on failure, which would improve completeness, but overall it is reasonably comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of additionalProperties and the override parameters for association type IDs, which are not fully detailed in the schema. This enhances understanding beyond the built-in 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?

Clearly states 'Create a HubSpot Quote and associate it to a deal and line items in a single operation.' It specifies the verb (Create) and resource (HubSpot Quote), and distinguishes itself as a high-level helper wrapping the standard endpoint, differentiating from siblings like hubspot_crm_create or hubspot_associations_create.

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 prerequisites: deal and line items must already exist, and suggests using hubspot_crm_create to create line items first. Provides guidance on overriding association type IDs and verifying IDs with hubspot_associations_labels_list. Mentions required scopes, giving clear context for when to use this tool versus 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 provided, the description discloses the batch nature, efficiency, and max limit. However, it omits behavioral details like error handling on partial failures or rate limits, leaving some gaps for an 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 two short, front-loaded sentences covering purpose, efficiency, constraints, and prerequisites with zero fluff. 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 simple input (one array parameter) and no output schema, the description sufficiently covers functionality, constraints, and requirements. Missing return format is minor; the batch read is self-explanatory.

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 reinforces the max items count and batch efficiency. While it adds context beyond the schema, the parameter is simple and well-documented in the schema itself.

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 'Read', resource 'multiple automation workflows', and differentiates from individual get calls and list operations, making the purpose highly specific and actionable.

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

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

Explicitly conveys when to use (efficient batch fetch), maximum IDs, and required OAuth scope. Lacks explicit when-not-to-use conditions, but the alternative is clearly stated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It notes the BETA status, required OAuth scope, and that complex fields require external documentation. However, it does not describe what the tool returns after creation, whether it is idempotent, or what errors might occur. This is a moderate gap for a mutation tool.

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

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

The description is concise with four sentences. The first sentence states the core purpose, the second clarifies required vs optional fields, the third warns about complex schema, and the fourth notes OAuth scope. No superfluous content, and it 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?

Given 7 parameters with 100% schema coverage and no output schema, the description covers creation intent, required fields, optional field deferral, external references for complex schemas, and auth. It lacks explicit mention of return value or error behavior, but overall it is fairly complete for a create 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 description coverage is 100%, so baselines at 3. The description adds value by emphasizing required fields, providing a practical usage hint for the 'type' enum (e.g., CONTACT_FLOW is most common), and warning about complex recursion in enrollmentCriteria. This extra context raises the score 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 creates an automation workflow in HubSpot Automation v4 API, using the verb 'Create' and specifying the resource. It mentions the BETA status and references the update sibling tool for post-creation configuration, but does not explicitly distinguish from other sibling tools like list or get.

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 identifies when to use this tool (to create a workflow), notes the required fields, and points to hubspot_workflows_update for subsequent configuration. It also mentions the required OAuth scope. However, it does not provide explicit 'when not to use' guidance or compare to other create tools for different objects.

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. Clearly warns that deletion is irreversible and cannot be undone via the API. Mentions OAuth scope requirement. Could add response format or side effects but is sufficient for a delete tool.

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

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

Concise, front-loaded with BETA and WARNING. Every sentence adds necessary context 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?

Completely covers what the tool does, its irreversible nature, alternative action, prerequisite step, and authentication requirement. No output schema, but for a delete tool this is adequate.

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 3. Description adds value by repeating the irreversibility warning and suggesting to confirm the flow ID first, which goes beyond 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?

Clearly states it deletes an automation workflow irreversibly. Specifies the resource and action, and is distinct from sibling workflow tools like get, list, create, 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?

Explicitly advises to consider disabling instead of deleting if the workflow might be needed later. Recommends using hubspot_workflows_get to confirm the flow ID before proceeding.

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 exist, so the description carries the burden. It declares BETA status and required OAuth scope, and clarifies that the result is 'campaign data linked to Send Email actions.' However, it does not disclose whether it is read-only, pagination details, or error behavior.

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: first states the primary purpose, second adds return details and auth requirement. No redundant 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 single-parameter tool with no output schema, the description adequately covers what it does and what it returns. Missing details like response structure or pagination are minor given 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?

Schema coverage is 100% with a clear property description. The description adds minor context by emphasizing 'v4 flow ID' and the type of data returned, but does not significantly extend 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 ('Get'), the resource ('email marketing campaigns'), and the context ('associated with a specific automation workflow'). It distinguishes from sibling tools like hubspot_workflows_get or hubspot_workflows_list by focusing on email campaigns linked to Send Email actions.

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

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

The description specifies the tool is for automation workflows in the v4 API and notes the required OAuth scope, providing clear context. However, it does not explicitly compare to siblings 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?

Discloses BETA status, OAuth scope requirement, and that it returns the full flow definition. As a read operation with no annotations, this is adequate, though rate limits or error handling are not mentioned.

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. Each sentence adds distinct information: action+API in first, return+auth in second. Front-loaded with the core 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 one required parameter, no output schema, and simple GET behavior, the description covers essential aspects: what it does, how to call it, what it returns, and authorization. No gaps 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 coverage is 100% with a clear description of flowId. The description reinforces the parameter's purpose (by its ID) and source (v4 API), adding value beyond the schema alone.

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

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

Clearly states it gets a single automation workflow by ID from HubSpot Automation v4 API, specifying the return content and required OAuth scope. Distinguishes from siblings like list and v3_get through API version and singular retrieval.

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

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

Describes when to use (when you have a specific flow ID) but does not explicitly mention when not to use or provide alternatives. The BETA tag and API version hint at context, but no direct comparison to 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 must cover behavioral traits. Mentions returns a mapping of legacyWorkflowId → v4 flowId and requires 'automation' OAuth scope. Does not explicitly state non-destructive nature, but mapping implies read-only. Acceptable.

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 filler. First sentence states core purpose, second adds usage guidance and mentions return value and scope requirement. Extremely 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?

For a simple mapping tool with one parameter and no output schema, the description provides return value info and required OAuth scope. Slightly lacking mention of error handling or limits, but sufficient for a mapping utility.

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

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

Schema description coverage is 100% for the single parameter 'workflowIds', which is fully described. The description adds context about migration but does not enhance parameter semantics beyond the schema. Baseline 3.

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

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

Clearly states the tool maps legacy v3 integer IDs to v4 string IDs, with specific verb 'map' and resource 'ID mappings'. Differentiates from sibling tools that perform CRUD or other workflow operations.

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 when migrating from the deprecated v3 Workflows API to the v4 Flows API, or when you have stored references to v3 workflow IDs'. Provides clear context for when to use, though no explicit comparison to 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?

Discloses Beta state, required OAuth scope, and return shape. No annotations provided, so description carries full burden and does 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?

Two sentences, no wasted words, front-loaded with key 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?

Explains return shape, pagination, OAuth scope, and Beta status. No output schema, but description compensates well.

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

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

Schema covers both parameters (100% coverage). Description adds context on pagination flow, explaining how 'after' is used, going beyond schema defaults.

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 automation workflows from HubSpot Automation v4 API, distinguishing it from sibling tools like create, delete, update.

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 pagination instructions using nextCursor and explains when to use the 'after' parameter. Does not explicitly mention alternatives, but siblings are clearly other operations.

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 fully disclose behavioral traits. It mentions BETA status and OAuth scope but fails to state that the operation is read-only, any rate limits, or potential 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 concise sentences: first states the purpose and return value, second states the required scope. No unnecessary words, well 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 tool with one parameter and no output schema, the description covers essential context: beta status, scope requirement, and key metrics returned. Minor gap: doesn't confirm it's a read operation.

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 only parameter, flowId, is fully described in the schema with coverage at 100%. The description text adds no additional meaning beyond the schema, 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?

Description clearly states the tool retrieves performance metrics for an automation workflow, with specific examples like enrollment counts and action completion rates. This distinguishes it from sibling tools that list or get workflow details.

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?

Specifies the required 'automation' OAuth scope, which is a key prerequisite. However, it does not explicitly describe when to use this tool over alternatives or exclusion criteria.

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 the full burden. It discloses that this is a PUT operation that replaces the entire workflow, resets omitted fields to defaults, and requires the 'automation' OAuth scope. This sufficiently communicates the tool's mutation behavior.

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

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

The description is three sentences long, front-loading the core purpose ('Fully replace'), then providing behavioral and prerequisite guidance. 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?

The description covers the essential operation, prerequisites, and behavioral traits. However, it does not describe the return value or response format, which is notable given the lack of an output schema. Still, the description is adequate for a mutation tool with clear documentation.

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 critical meaning: 'Fields not included in the request body will be reset to their defaults.' This clarifies parameter behavior beyond the schema, explaining the effect of omission. The suggestion to use get first also adds value.

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

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

The description states 'Fully replace an existing automation workflow' via a PUT operation, clearly specifying the verb and resource. It differentiates from sibling tools like hubspot_workflows_get by advising to fetch current state before updating.

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 hubspot_workflows_get first to fetch current state, providing clear context. It explains the full replacement behavior but does not explicitly state 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?

No annotations exist, but the description only notes it's a legacy GET. It does not disclose authentication needs, error conditions, or response format. For a simple read tool, more context is expected.

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: one for purpose, one for usage guidance. No fluff, front-loaded with 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?

For a simple one-parameter GET with no output schema, the description adequately covers purpose and usage. Missing a brief note on return value but still complete enough for selection.

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 well-described integer parameter. Description adds legacy context but no additional parameter meaning beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Get a single Workflow by ID using the HubSpot Automation v3 API'. Verb and resource are specific, and the legacy API note distinguishes it from v4 versions and sibling tools like hubspot_workflows_get.

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 against using for new integrations ('prefer Automation v4 flows for new integrations'), providing clear when-to-use context and an alternative.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It only states it returns a flat list of workflow definitions, but does not disclose that it's read-only, safe to call, or details about pagination, authentication needs, or any side effects. The lack of behavioral context is a significant gap for a tool with zero annotation coverage.

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

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

The description is extremely concise with two sentences that efficiently convey the tool's purpose, legacy status, and return format. Every sentence adds value without any fluff.

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

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

For a list tool with two parameters and no output schema, the description provides the basic purpose and return format ('flat list of workflow definitions'). However, it omits details about pagination behavior, ordering, and what the definitions contain. The information is adequate but not fully complete for an agent to understand all aspects of the tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (limit and offset) with descriptions. The tool description does not add any additional meaning or context beyond what the schema provides, meeting the baseline expectation.

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

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

The description clearly states it lists all workflows using the HubSpot Automation v3 API, with a specific verb ('List') and resource ('Workflows'). The '[LEGACY]' prefix distinguishes it from potential v4 alternatives, and it explicitly notes it's the legacy API, helping the agent differentiate it 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?

The description advises to prefer Automation v4 flows for new integrations, providing explicit when-to-use and when-not-to-use guidance. While it doesn't name the exact alternative tool, it gives clear context to avoid using this v3 API for new work.

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