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

The description adds valuable behavioral context beyond what annotations provide. While annotations indicate this is a non-destructive, idempotent write operation (readOnlyHint: false, destructiveHint: false, idempotentHint: true), the description warns about data modification and specifies a batch limit ('max 100 associations per batch') in the schema. However, it doesn't mention authentication requirements or rate limits, which would be helpful for a batch 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 well-structured with clear sections (Guardrails, Purpose, Prerequisites) and uses emojis for visual organization. Each sentence adds value, though the 'Purpose' section could be more concise by combining its two points into one sentence. Overall, it's appropriately sized for a batch operation tool with important prerequisites.

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 association creation with 4 required parameters) and the absence of an output schema, the description provides good contextual coverage. It explains the tool's purpose, includes important warnings and prerequisites, and references sibling tools for obtaining necessary data. However, it doesn't describe what the tool returns or potential error conditions, which would be helpful since there's 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?

With 100% schema description coverage, the input schema already thoroughly documents all 4 parameters. The description doesn't add significant parameter semantics beyond what's in the schema, though it does mention 'Uses a single set of association types for all associations in the batch' which helps explain the 'types' parameter's purpose. This meets the baseline for high schema coverage.

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

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

The description explicitly states the tool 'Establishes relationships between HubSpot objects, linking records across different object types, by creating associations between objects in batch.' This provides a specific verb ('creates associations'), resource ('HubSpot objects'), and scope ('in batch'), clearly distinguishing it from sibling tools like hubspot-list-associations or hubspot-get-association-definitions.

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

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

The description provides explicit guidance on when to use this tool versus alternatives. It includes a 'Data Modification Warning' stating to 'Only use when the user has explicitly requested to update their CRM,' and lists prerequisites that reference sibling tools (hubspot-get-user-details, hubspot-get-association-definitions) for obtaining necessary information before creating associations.

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

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

Annotations already indicate this is a non-readOnly, non-destructive, non-idempotent operation. The description adds valuable context beyond annotations: the data modification warning, the bulk optimization nature, and the prerequisite steps needed for successful execution. However, it doesn't mention rate limits, error handling, or what happens on partial failures in the batch.

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

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

The description is well-structured with clear sections (Guardrails, Purpose, Prerequisites) and uses emojis for visual organization. Each sentence earns its place by providing distinct guidance. It could be slightly more concise by combining some points, but overall it's efficiently organized and front-loaded with important warnings.

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 creation tool with comprehensive annotations and 100% schema coverage, the description provides good contextual completeness. It covers the mutation nature, prerequisites, and bulk optimization purpose. The main gap is the lack of output schema, so the description doesn't explain what the tool returns, but given the annotations and schema coverage, it's reasonably 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 description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline score of 3 is appropriate when the schema does all the heavy lifting for parameter documentation.

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

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

The description explicitly states the tool's purpose: 'Creates multiple HubSpot objects of the same objectType in a single API call, optimizing for bulk operations.' This is a specific verb ('creates') with clear resource ('HubSpot objects') and distinguishes it from siblings like hubspot-create-engagement (single engagement) or hubspot-batch-update-objects (updates instead of creates).

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

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

The description provides explicit guidance on when to use this tool: 'Only use when the user has explicitly requested to update their CRM.' It also lists three prerequisite tools (hubspot-get-user-details, hubspot-list-objects, hubspot-get-association-definitions) that should be used before invoking this tool, giving clear context for 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds valuable context about batch operation and the 100-item limit (implied by 'multiple'), which isn't in annotations. It doesn't describe rate limits or auth needs, but with good annotation coverage, this is 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 well-structured with emoji headings and bullet points, making it easy to scan. Both sentences are relevant and add value. It could be slightly more concise by combining points, but it's efficient overall with no wasted words.

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

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

For a read operation with rich annotations (readOnlyHint, idempotentHint) and full schema coverage, the description is reasonably complete. It covers purpose and usage well. However, without an output schema, it doesn't describe return values (e.g., format, error handling), leaving a minor gap for a batch 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 fully documents all 4 parameters. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., it doesn't explain 'objectType' values or 'properties' usage). Baseline 3 is appropriate when the schema does the heavy lifting.

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 specific action ('retrieves multiple HubSpot objects'), resource ('objects of the same object type'), and scope ('by their IDs in a single batch operation'). It distinguishes from siblings like 'hubspot-list-objects' (list all) and 'hubspot-search-objects' (search with criteria) by specifying retrieval by known IDs in batch mode.

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

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

The description provides explicit guidance on when to use ('when the object IDs are known'), which is clear and helpful. However, it doesn't mention when NOT to use or name specific alternatives (e.g., 'hubspot-list-objects' for listing all objects or 'hubspot-search-objects' for searching without IDs), which prevents a perfect score.

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

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

The description adds valuable behavioral context beyond annotations. Annotations indicate it's not read-only, not destructive, not idempotent, and open-world. The description adds a data modification warning, clarifies it's for updating existing objects (not creating), mentions batch limits (up to 100 per batch implied via schema), and provides debugging hints (objectWriteTraceId). It doesn't contradict annotations, as 'modifies HubSpot data' aligns with readOnlyHint=false.

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

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

The description is well-structured with emoji-labeled sections (Guardrails, Purpose, Prerequisites), making it easy to scan. It's appropriately sized for a batch update tool with prerequisites, though some sentences could be more concise (e.g., the Purpose section has slightly repetitive phrasing). Overall, it's front-loaded with critical warnings and purpose, with no wasted text.

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

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

Given the tool's complexity (batch update with prerequisites), the description is mostly complete. It covers purpose, usage guidelines, warnings, and prerequisites. However, there's no output schema, and the description doesn't explain return values or error handling, which is a minor gap. Annotations provide safety context (e.g., not destructive), and schema covers parameters well, so it's largely adequate but could benefit from output details.

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 all parameters thoroughly. The description doesn't add significant parameter-specific semantics beyond what's in the schema (e.g., it mentions objectType but doesn't elaborate beyond schema's enum-like list). It implies batch size via 'multiple' and references prerequisites for property identification, but these are general usage tips rather than parameter explanations. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: 'Updates multiple existing HubSpot objects of the same objectType in a single API call.' It specifies the verb ('updates'), resource ('HubSpot objects'), scope ('multiple'), and constraint ('same objectType'), and distinguishes it from siblings like hubspot-batch-create-objects (create vs. update) and hubspot-update-engagement (specific object type vs. general).

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

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

The description provides explicit guidance on when to use this tool: 'Use this tool when the user wants to update one or more existing CRM objects.' It also includes prerequisites (e.g., use hubspot-get-user-details for OwnerId/UserId, hubspot-list-objects for sampling) and alternatives for uncertainty (e.g., use hubspot-list-properties if hubspot-list-objects isn't helpful), clearly differentiating it from other tools.

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

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

Annotations already indicate this is a write operation (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds valuable context beyond annotations: the data modification warning, HTML formatting support with caveats about headings, and that this feeds activity reporting in the CRM. However, it doesn't mention rate limits, error conditions, or what happens on duplicate creation attempts.

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 uses clear section headers (Guardrails, Purpose, Prerequisites, Usage Guidance) that make it easy to scan. Each section contains relevant information with minimal redundancy. While not the absolute most concise possible, every sentence serves a purpose and the structure helps with comprehension.

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 creation tool with 5 parameters, 100% schema coverage, and annotations covering key behavioral aspects, the description provides good additional context. It covers prerequisites, usage scenarios, limitations (unsupported engagement types), and formatting considerations. The main gap is the lack of output schema or description of return values, but given the annotations and schema coverage, this is reasonably 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 description coverage is 100%, so the schema already documents all parameters well. The description adds meaningful context about parameter usage: it explains the difference between NOTE and TASK types, mentions that associations are required to connect to CRM records, and references the prerequisite hubspot-get-user-details tool for obtaining ownerId. It doesn't add syntax details but provides practical usage guidance.

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

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

The description explicitly states the tool 'creates a HubSpot engagement (Note or Task) associated with contacts, companies, deals, or tickets' - a specific verb+resource combination. It distinguishes this tool from siblings like hubspot-update-engagement (updates existing engagements) and hubspot-get-engagement (reads engagements), making the purpose clear and differentiated.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Only use when the user has explicitly requested to update their CRM' (guardrail), 'Use NOTE type for adding notes to records' and 'Use TASK type for creating tasks with subject, status, and assignment' (type-specific guidance), and 'Other types of engagements (EMAIL, CALL, MEETING) are NOT supported yet' (clear exclusion). It also references the prerequisite tool hubspot-get-user-details.

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

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

The description adds valuable behavioral context beyond annotations: it warns about data modification ('modifies HubSpot data') and emphasizes user confirmation, which complements the annotations (readOnlyHint=false, destructiveHint=false). However, it doesn't mention potential side effects like rate limits or authentication requirements, leaving some gaps in behavioral disclosure.

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 structured with emoji headings, which aids readability but adds visual clutter. It includes some redundant information (e.g., repeating the purpose in 'Usage Guidance'), and the prerequisites section could be more concise. However, it's front-loaded with key warnings and purpose, and most sentences earn their place by providing actionable guidance.

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

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

Given the tool's complexity (14 parameters, mutation operation) and lack of output schema, the description does well by covering prerequisites, usage guidance, and behavioral warnings. It compensates for the absence of output schema by guiding users to other tools for context. However, it could better explain error handling or response format to be fully 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 description coverage is 100%, so the schema already documents all 14 parameters thoroughly. The description adds no specific parameter semantics beyond what's in the schema, such as explaining relationships between parameters (e.g., 'options' is only for 'enumeration' type). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description explicitly states 'Creates new custom properties for HubSpot object types' with a specific verb ('creates') and resource ('custom properties'), clearly distinguishing it from sibling tools like hubspot-update-property (updates existing properties) and hubspot-create-objects (creates objects, not properties). The purpose is precise and differentiated.

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

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

The description provides explicit guidance on when to use this tool ('when you need to create a new custom property'), when not to use it ('not create an object of a specific object type'), and alternatives to consider first (list-properties to check for existing properties). It also includes prerequisites and sibling tool references for context.

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

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

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds context about proactive use and feedback purpose, which enhances understanding beyond annotations. No contradiction with annotations.

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

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

The description is structured with bullet points but includes repetitive elements (e.g., multiple 'Use this tool' phrases) and could be more front-loaded. It's appropriately sized but not maximally efficient.

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

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

Given 0 parameters, no output schema, and rich annotations, the description is complete enough for a feedback tool. It covers purpose, usage, and context adequately, though it could briefly mention the feedback mechanism (e.g., link generation).

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 are 0 parameters, and schema description coverage is 100%. The description doesn't need to explain parameters, so a baseline of 4 is appropriate as it focuses on usage rather than input 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 states the tool's purpose is to generate a feedback link for HubSpot MCP tools, which is clear but not specific about the verb+resource combination. It distinguishes from siblings by focusing on feedback rather than data operations, but lacks explicit differentiation in terms of functionality.

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

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

The description provides explicit usage scenarios: when the user wants to submit feedback, when other tools fail, or when sensing user dissatisfaction. It clearly outlines when to use this tool versus alternatives, with specific context and exclusions.

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

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

Annotations already indicate this is a read-only, non-destructive, idempotent operation with open-world data, so the description doesn't need to repeat those safety aspects. However, it adds valuable context about the tool's role in validation workflows ('to ensure valid relationship types or to help troubleshoot'), which goes beyond what annotations provide. No contradiction with annotations exists.

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

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

The description is well-structured with emoji-labeled sections (Purpose, Returns, Usage Guidance), each containing a single, focused sentence. It is front-loaded with the core purpose, avoids redundancy, and every sentence contributes directly to understanding the tool's use. No wasted words.

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

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

Given the tool's moderate complexity (2 required parameters, no output schema), the description is largely complete: it states the purpose, return format, and usage context. However, it could slightly enhance completeness by mentioning that it returns an array of definitions with details like type IDs, labels, and categories, though this is implied in the Returns section. Annotations cover safety aspects 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?

The input schema has 100% description coverage, fully documenting both parameters (fromObjectType and toObjectType) with valid values and guidance for custom objects. The description does not add any parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without extra value.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieves') and resources ('valid association types between specific HubSpot object types'), distinguishing it from sibling tools like hubspot-list-associations (which lists actual associations) and hubspot-get-schemas (which gets object schemas). The purpose is precise and unambiguous.

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

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

The description provides explicit guidance on when to use this tool ('Always use before creating associations to ensure valid relationship types or to help troubleshoot association creation errors'), which clearly differentiates it from alternatives like hubspot-batch-create-associations (for creating) and hubspot-list-associations (for listing existing ones). It gives a concrete use case and timing.

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

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

Annotations already provide comprehensive behavioral hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true). The description adds no additional behavioral context about rate limits, authentication requirements, error conditions, or what constitutes a valid engagement ID beyond the schema's exclusiveMinimum constraint.

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 just one clear sentence. The emoji and numbered formatting add visual structure without unnecessary verbosity. Every word serves a purpose with zero wasted content.

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

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

For a simple read operation with comprehensive annotations and full schema coverage, the description is minimally adequate. However, without an output schema, the description doesn't indicate what information is returned about engagements (e.g., fields, structure, or relationship to other HubSpot objects), leaving a gap in understanding the tool's full 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?

With 100% schema description coverage, the input schema already fully documents the single 'engagementId' parameter. The description adds no additional semantic context about what an engagement ID represents, format examples, or how to obtain valid IDs beyond what's in the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('HubSpot engagement by ID'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate itself from sibling tools like 'hubspot-list-objects' or 'hubspot-search-objects' which might also retrieve engagements in different ways.

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

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

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'hubspot-list-objects', 'hubspot-search-objects', and 'hubspot-batch-read-objects' available, there's no indication whether this is for single-record lookups versus bulk operations or filtered searches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-destructive operations. The description adds valuable behavioral context beyond annotations: 'Validates that object type IDs exist in the HubSpot system' and clarifies it generates UI links rather than performing data mutations. No contradiction with annotations.

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

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

The description is well-structured with clear sections (Purpose, Prerequisites, Usage Guidance), front-loaded with the core purpose, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

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

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

Given the tool's moderate complexity, 100% schema coverage, and comprehensive annotations, the description is mostly complete. It covers purpose, prerequisites, usage, and validation behavior. The main gap is no output schema, but the description doesn't need to explain return values extensively for a link generation 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 all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, mainly reinforcing that parameters come from hubspot-get-user-details and object types/IDs must be valid. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description explicitly states the tool 'Generates HubSpot UI links for different pages based on object types and IDs' and distinguishes it from siblings by specifying it's for link generation rather than data operations like create, read, update, or search. It clearly identifies the verb (generates) and resource (HubSpot UI links).

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 guidance: 'Use to generate links to HubSpot UI pages when users need to reference specific HubSpot records' and includes prerequisites ('Use the hubspot-get-user-details tool to get the PortalId and UiDomain'). It clearly states when to use this tool and references an alternative tool for prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds some context by specifying the scope of metadata retrieved (type, options, configuration details), but doesn't disclose additional behavioral traits like rate limits, authentication needs, or error handling. No contradiction with annotations exists.

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

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

The description is appropriately sized and front-loaded with a clear purpose statement. It uses two concise bullet points with no wasted words, though the emoji and formatting slightly reduce efficiency. Every sentence earns its place by reinforcing the tool's function.

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

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

Given the tool's moderate complexity (2 required parameters), rich annotations (covering safety and idempotency), and no output schema, the description is mostly complete. It explains what the tool does and the metadata scope, but could benefit from mentioning return format or error scenarios to fully compensate for the lack of 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 description coverage is 100%, with both parameters (objectType and propertyName) well-documented in the schema. The description doesn't add meaningful semantic details beyond what the schema provides, such as examples or edge cases. Baseline 3 is appropriate since the schema handles parameter documentation adequately.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieves detailed information', 'get all metadata') and resources ('specific property for a HubSpot object type'). It distinguishes itself from sibling tools like hubspot-list-properties (which lists properties) by focusing on retrieving detailed metadata for a single property.

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

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

The description provides clear context for when to use this tool ('to get all metadata related to a property'), but it doesn't explicitly mention when not to use it or name specific alternatives. For example, it doesn't contrast with hubspot-list-properties for browsing properties or hubspot-get-schemas for custom objects, though the schema hints at the latter.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds value by specifying the return format ('Provides the objectTypeId and objectType for each schema') and how to use these attributes in subsequent requests, which is useful context beyond annotations. No contradictions exist.

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

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

The description is well-structured with emoji-labeled sections (🎯 Purpose, 🧭 Usage Guidance, 📦 Returns), front-loading key information. Each sentence earns its place by providing essential details without redundancy. It's appropriately sized for a zero-parameter tool.

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

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

Given the tool's zero parameters, rich annotations (covering safety and behavior), and no output schema, the description is complete. It explains the purpose, usage context, and return format clearly. For a read-only schema retrieval tool, this provides all necessary context for an AI agent.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on output semantics, explaining what the tool returns and how to use the results. This adds meaningful value beyond the schema.

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

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

The description clearly states the specific verb ('Retrieves') and resource ('all custom object schemas defined in the HubSpot account'), distinguishing it from siblings like hubspot-list-objects or hubspot-get-property which handle different resources. The purpose is precise and unambiguous.

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

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

The description explicitly states when to use this tool: 'Before working with custom objects to understand available object types, their properties, and associations.' This provides clear context and distinguishes it from alternatives like hubspot-list-objects (which lists instances, not schemas) or hubspot-get-property (which retrieves property definitions, not object schemas).

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

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

Annotations already indicate this is a read-only, non-destructive, idempotent operation with open-world semantics. The description adds valuable context beyond this: it explains that the tool authenticates and analyzes tokens, provides permission context, and returns specific data like user ID, hub ID, and API scopes. It also mentions practical uses like constructing HubSpot UI URLs. No contradiction with annotations exists.

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

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

The description is well-structured with clear sections (Purpose, Usage Guidance, Returns) and uses bullet points efficiently. Every sentence adds value: the purpose statement is specific, the usage guidance is directive, and the returns section explains what data is provided and how it can be used. 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 zero-parameter tool with comprehensive annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) but no output schema, the description provides excellent context. It explains the tool's purpose, when to use it, and details the return values including user ID, hub ID, API scopes, and practical applications. This gives the agent everything needed to understand and invoke this tool correctly.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose and output. This meets the baseline expectation for a zero-parameter tool.

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

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

The description explicitly states the tool's purpose: 'Authenticates and analyzes the current HubSpot access token, providing context about the user's permissions and account details.' This clearly distinguishes it from sibling tools (which focus on objects, properties, workflows, etc.) by specifying it's about user authentication and permission analysis rather than data 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?

The description provides explicit usage guidance: 'This tool must be used before performing any operations with Hubspot tools to determine the identity of the user, and permissions they have on their Hubspot account.' This tells the agent exactly when to use it (as a prerequisite) and why, distinguishing it from all sibling tools that perform actual HubSpot 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?

The description adds valuable context beyond annotations by specifying what information is returned ('complete workflow information including actions, enrollment criteria, and scheduling'), which helps the agent understand the output format. Annotations already cover read-only, non-destructive, idempotent, and open-world hints, so the description appropriately focuses on behavioral details not captured in structured fields.

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

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

The description is well-structured with clear sections (Purpose, Usage Guidance), uses bullet points efficiently, and every sentence adds value without redundancy. It's appropriately sized and front-loaded with essential information.

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

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

Given the tool's simplicity (1 parameter, 100% schema coverage, rich annotations), the description is mostly complete. It explains purpose, usage flow, and output content. The main gap is the lack of an output schema, but the description compensates by detailing what information is returned. For a read-only tool with good annotations, this is sufficient.

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

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

Schema description coverage is 100%, with the single parameter 'flowId' fully documented in the schema. The description mentions the parameter but doesn't add semantic details beyond what the schema provides (e.g., format examples or constraints). This meets the baseline of 3 for high schema coverage.

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

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

The description explicitly states the tool's purpose as 'retrieves detailed information about a specific workflow from the HubSpot account,' which is a clear verb+resource combination. It distinguishes itself from sibling tools like hubspot-list-workflows (which lists workflows) by focusing on retrieving details for a specific workflow ID.

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

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

The description provides explicit guidance on when to use this tool: 'Use the hubspot-list-workflows tool first to identify the workflow ID you need.' This clearly indicates the prerequisite and alternative tool, helping the agent understand the workflow for proper tool selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering safety and scope. The description adds valuable behavioral context beyond annotations: it explains the return format ('Collection of associated object IDs and relationship metadata'), suggests a follow-up action ('Use hubspot-batch-read-objects to get more information'), and clarifies the tool's focus on existing relationships rather than property-based filtering. No contradictions with annotations exist.

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

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

The description is well-structured with clear sections (Purpose, Returns, Usage Guidance), uses bullet points for readability, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity and front-loads key information efficiently.

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

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

Given the tool's moderate complexity, rich annotations (covering read-only, non-destructive, open-world behavior), and 100% schema coverage, the description is complete. It explains the tool's purpose, usage context, return format, and integration with other tools (hubspot-batch-read-objects), addressing all necessary aspects without needing an 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 description coverage is 100%, so the schema fully documents all parameters. The description doesn't add specific parameter details beyond what the schema provides, such as explaining the relationship between objectType and toObjectType or clarifying the 'after' parameter's pagination role. However, it implies the tool's purpose involves these parameters through examples, meeting the baseline for high schema coverage.

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

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

The description explicitly states the tool's purpose with specific verbs ('retrieves existing relationships') and resources ('between a specific object and other objects of a particular type'), and provides concrete examples (e.g., 'all companies that a contact is associated with'). It clearly distinguishes this tool's relationship-mapping function from other tools in the sibling 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?

The description provides explicit guidance on when to use this tool ('when mapping relationships,' 'when you already know a specific record's ID'), when not to use it ('Prefer this over hubspot-search-objects tool when exploring established connections rather than filtering by properties or criteria'), and names a specific alternative tool (hubspot-search-objects). This gives clear context for tool selection.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=false, covering safety and idempotency. The description adds value by specifying 'paginated list' (implying pagination behavior) and 'initial data exploration' (context for usage), but doesn't detail rate limits or auth needs. No contradiction with annotations.

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

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

The description is well-structured with emoji headings (🎯, 📦, 🧭) and bullet points, making it easy to scan. Each sentence adds value: purpose, returns, and usage guidance. No wasted words, and it's 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 the tool's complexity (6 parameters, 1 required), rich annotations (readOnlyHint, openWorldHint, etc.), and 100% schema coverage, the description is complete. It covers purpose, returns, and usage guidance, and while there's no output schema, it mentions 'Collection of objects with their properties and metadata, plus pagination information,' which is sufficient.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., it mentions 'specified type' but doesn't elaborate on objectType options). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Retrieves a paginated list of objects of a specified type from HubSpot.' This is specific (verb: 'retrieves', resource: 'objects'), and it distinguishes from siblings by explicitly mentioning 'paginated list' and 'specified type', which differentiates it from search or batch 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?

The description provides explicit guidance on when to use this tool vs. alternatives: 'Use for initial data exploration...', 'Use hubspot-search-objects for targeted queries...', 'Use hubspot-batch-read-objects to retrieve specific objects...', and 'Use hubspot-list-associations to list associations...'. This covers both when-to-use and when-not-to-use scenarios with named alternatives.

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

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

The description adds valuable behavioral context beyond annotations: it warns about 'large response that can consume a lot of tokens', which is important operational guidance not covered by the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint annotations. This disclosure helps the agent manage token usage effectively.

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 efficiently structured with clear sections (Purpose, Usage Guidance) using emoji markers. Each sentence serves a distinct purpose: stating the core function, providing token usage warning, suggesting alternatives, and indicating workflow timing. There's no wasted text or 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 rich annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and 100% schema coverage, the description provides excellent context for a read-only listing tool. The only minor gap is the lack of output schema, but the description compensates by warning about large responses. It effectively guides the agent on when and how to use this 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?

With 100% schema description coverage, the input schema already fully documents all three parameters (objectType, archived, includeHidden). The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline expectation but doesn't provide extra value in this dimension.

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

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

The description explicitly states the verb 'retrieves' and resource 'complete catalog of properties for any HubSpot object type', making the purpose specific and clear. It distinguishes from sibling tools like hubspot-get-property (specific property) and hubspot-list-objects (objects rather than properties), providing clear differentiation.

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

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

The description provides explicit guidance on when to use alternatives: 'Use the hubspot-list-objects tool to sample existing objects first' and 'Try to use the hubspot-get-property tool to get a specific property'. It also advises 'Use at the beginning of workflows to understand available data structures', giving clear context for appropriate usage scenarios.

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

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

Annotations already provide strong behavioral hints (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false), so the description doesn't need to repeat safety information. It adds useful context about pagination mechanics and the type of information returned (ID, name, type, status), which complements the annotations but doesn't provide rich additional behavioral details like rate limits or authentication requirements.

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

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

The description is well-structured with clear sections (Purpose and Usage Guidance), uses bullet points efficiently, and contains no redundant or unnecessary information. Every sentence serves a purpose, making it easy to scan and understand quickly.

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 annotations cover safety and behavioral aspects, and the schema fully documents parameters, the description provides adequate context for a list operation. However, without an output schema, the description could benefit from more detail about the response structure beyond 'essential workflow information including ID, name, type, and status,' such as pagination metadata format or example 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?

With 100% schema description coverage, the input schema already fully documents both parameters ('limit' and 'after') with their constraints and purposes. The description reiterates this information in the Usage Guidance section but doesn't add significant semantic value beyond what's in the schema, meeting the baseline expectation for high schema coverage.

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

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

The description clearly states the tool 'retrieves a paginated list of workflows from the HubSpot account,' which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'hubspot-get-workflow' (singular) or 'hubspot-list-objects,' which might cause confusion about when to use this specific list operation versus other listing 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 provides clear guidance on how to use the 'limit' and 'after' parameters for pagination control, which is helpful for practical implementation. However, it lacks explicit guidance on when to use this tool versus alternatives like 'hubspot-get-workflow' for single workflows or 'hubspot-list-objects' for other HubSpot entities, leaving some contextual gaps.

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

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

The description adds valuable behavioral context beyond annotations: it explains the tool automatically sets the refreshed token in process.env.PRIVATE_APP_ACCESS_TOKEN (an important side effect), specifies rate limiting guidance ('do not invoke more than once per session'), and clarifies authentication requirements. Annotations already indicate idempotent and non-destructive, but the description provides practical usage constraints that aren't captured in structured fields.

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 efficiently structured with emoji-labeled sections (🔄, 🎯, 🛡️) that make it scannable. Each sentence adds value: the first states the core action, the Purpose section provides usage context, and the Guardrails section adds important constraints. There's no wasted text or redundancy.

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

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

For a parameterless token refresh tool with comprehensive annotations (idempotent, non-destructive) and no output schema, the description provides complete context. It covers when to use, prerequisites, behavioral effects (sets environment variable), and usage constraints. The combination of structured annotations and descriptive text gives the agent everything needed to use this tool correctly.

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

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

The tool has zero parameters with 100% schema description coverage, so the baseline would be 4. The description appropriately doesn't discuss parameters since none exist, and instead focuses on the tool's operational context and effects, which is the right approach for a parameterless tool.

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 specific action ('refreshes the HubSpot OAuth access token') and resource ('using the refresh token from environment variables'). It distinguishes this tool from all sibling tools, which perform CRUD operations on HubSpot data objects rather than token management.

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

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

The description provides explicit guidance on when to use ('when HubSpot API requests fail due to expired tokens'), when not to use ('not required for long-lived Private App tokens'), and prerequisites ('only use if using OAuth with REFRESH_TOKEN present'). It also specifies an alternative scenario ('do not invoke more than once per session unless a 401 Unauthorized response is received').

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, indicating safe read operations. The description adds valuable behavioral context beyond annotations: pagination information in returns, complex boolean logic capabilities, and specific limits (max 5 filterGroups, 6 filters per group, 18 total filters). It doesn't mention rate limits or authentication needs, but provides substantial operational guidance.

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 uses clear section headers (🎯 Purpose, 📋 Prerequisites, etc.) and is appropriately front-loaded with purpose. While comprehensive, some sections could be more concise - the filtering capabilities explanation is detailed but could be streamlined. Overall structure is logical with minimal wasted 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 complex search tool with 7 parameters, 100% schema coverage, and no output schema, the description provides excellent contextual completeness. It covers purpose, prerequisites, returns, usage guidance, and filtering capabilities. The main gap is lack of output format details, but given the annotations and comprehensive parameter documentation, this is a minor omission.

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

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

With 100% schema description coverage, the baseline is 3. The description adds some semantic context for filterGroups (explaining OR/AND logic relationships) and mentions the 'query' parameter searches 'default searchable properties,' but doesn't significantly enhance understanding of individual parameters beyond what's already well-documented in the schema.

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

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

The description clearly states the tool performs 'advanced filtered searches across HubSpot object types using complex criteria.' This specifies both the verb ('searches') and resource ('HubSpot object types') while distinguishing it from simpler list tools through the 'advanced filtered' and 'complex criteria' qualifiers.

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 'Usage Guidance' section explicitly states when to use this tool ('targeted data retrieval when exact filtering criteria are known') and provides three specific alternatives: hubspot-list-objects (when filter criteria unclear), hubspot-batch-read-objects (for retrieval by IDs), and hubspot-list-associations (for associations). It also includes prerequisites for sampling 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?

The description adds valuable behavioral context beyond annotations: the guardrails warn about data modification and user consent requirements, usage guidance explains partial updates ('Only include fields you want to update'), and HTML formatting limitations. Annotations cover idempotency and non-destructive nature, but the description provides practical implementation details that help the agent use the tool correctly.

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 uses clear section headers (Guardrails, Purpose, Prerequisites, Usage Guidance) that make it easy to scan. Each section contains focused, relevant information with minimal fluff. While slightly longer than minimal, every sentence serves a clear purpose in guiding tool usage.

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

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

For a mutation tool with good annotations (idempotent, non-destructive) but no output schema, the description provides strong context: guardrails for safety, prerequisites for successful invocation, and usage guidance for effective application. It covers the critical aspects needed to use this update tool correctly, though doesn't describe return values or error cases.

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 all parameters thoroughly. The description doesn't add significant parameter-specific information beyond what's in the schema descriptions. It mentions engagement ID as a prerequisite and owner ID needing to be fetched, but these don't enhance understanding of the parameters themselves 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 explicitly states 'Updates an existing HubSpot engagement (Note or Task)' with specific verbs ('updates', 'modification') and resources ('engagement', 'attributes, content, and metadata'). It clearly distinguishes from sibling tools like hubspot-create-engagement (create vs. update) and hubspot-get-engagement (read vs. 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 provides explicit guidance on when to use ('Use for updating NOTE content or TASK details'), when not to use (only when user explicitly requests CRM updates per guardrails), and alternatives ('Use the hubspot-get-engagement tool to get current details', 'Use the hubspot-get-user-details tool to get owner ID'). It also distinguishes from create operations by emphasizing it updates existing engagements.

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

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

The description adds valuable context beyond annotations: the 'Data Modification Warning' explicitly states this tool modifies HubSpot data and should only be used when the user explicitly requests CRM updates. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description reinforces this is a mutation tool but not destructive. However, it doesn't describe rate limits, authentication requirements, or what happens when updating non-existent properties.

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

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

The description is well-structured with clear sections (Guardrails, Purpose, Usage Guidance) using emojis for visual organization. Each section contains 1-2 bullet points that are directly relevant. However, the Purpose section could be more concise, and some redundancy exists between the Guardrails warning and what annotations already convey.

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 mutation tool with 12 parameters and no output schema, the description provides adequate but not comprehensive context. It covers purpose, guardrails, and usage guidance but doesn't explain what the tool returns or provide examples of successful updates. Given the complexity and lack of output schema, more information about response format would be helpful.

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

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

With 100% schema description coverage, the input schema already documents all 12 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.

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

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

The description clearly states the tool 'updates existing custom properties for HubSpot object types, enabling data structure customization.' This is a specific verb (updates) with resource (custom properties) and context (HubSpot object types). However, it doesn't explicitly distinguish this from sibling tools like 'hubspot-create-property' or 'hubspot-get-property' beyond the 'update' 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 provides clear usage guidance: 'Use hubspot-list-objects tool to sample existing objects for the object type' and 'If hubspot-list-objects tool's response isn't helpful, use hubspot-list-properties tool.' This gives practical steps for when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives like 'hubspot-create-property' for creating new properties instead of updating existing ones.

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