hubspot-conversations-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.4.0
Disambiguation2/5
Several tools have overlapping purposes, such as GetChannelAccountDetails vs RetrieveChannelAccountDetails and UpdateConversationThread vs ArchiveConversationThread, which both handle archiving. The distinction between general and custom channel tools is not immediately clear, making misselection likely.
Naming Consistency2/5
Tool names mix Get, Retrieve, List, Update, Create, Send, Publish, and Archive without a consistent pattern. For example, 'GetChannelAccountDetails' and 'RetrieveChannelAccountDetails' are nearly identical in structure but use different verbs. The naming lacks a predictable verb_noun convention.
Tool Count3/5
With 24 tools, the server is on the heavy side, though the HubSpot Conversations domain is broad enough to warrant many operations. However, several tools (like the multiple channel account retrieval variants) could be consolidated, making the count feel inflated.
Completeness4/5
The tool set covers the essential conversation lifecycle: listing and retrieving threads, sending and viewing messages, managing inboxes/channels/accounts, and archiving. Minor gaps exist, such as no way to create a thread or update an assignment, but these are not critical for typical workflows.
Average 3.9/5 across 24 of 24 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 18 commits in the last 12 weeks
- Last stable release on August 16, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation covers the safety profile, so the description doesn't need to restate that. However, it mentions 'optional filters' that are not supported by the input schema, which is misleading. It also adds no meaningful behavioral context such as return format, pagination behavior, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that names the action and resource, with examples. It is concise, though 'if needed' is filler and the unsupported 'filters' claim slightly detracts from precision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (read-only, 3 optional params, no output schema), the description is mostly adequate. It lacks explicit return-value details and pagination behavior, and it does not differentiate itself from similar list tools. Still, it provides enough to understand the basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all three parameters with 100% coverage, so the baseline is 3. The description adds 'sorting if needed' which aligns with the sort parameter, but the 'filters' mention is unsupported and adds no real semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of conversation channels and provides concrete examples (email, live chat, forms, WhatsApp), which distinguishes it from sibling tools like ListConversationInboxes or RetrieveChannelDetails. The mention of 'optional filters and sorting' is slightly overreaching since no filter parameter exists, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to get a list of channels) and mentions optional sorting, but it does not explicitly contrast it with sibling tools or state when not to use it. The absence of any alternative guidance or exclusions keeps this at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It implies a mutation through 'Update' but does not describe side effects, reversibility, authorization needs, or error handling. The only extra detail is the conditional error message for FAILED status, which is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise two-sentence summary, front-loaded with the main purpose and then a helpful conditional note. Every sentence earns its place, with no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a mutation tool. It does not explain return values, potential errors, preconditions, or the impact of the update. The agent lacks critical context for safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 recounts the enum values and the conditional error message parameter, but does not add meaning beyond what the schema already provides. It adds no new semantic depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (update delivery status) and the resource (message within a custom channel), enumerating the allowed statuses (SENT, FAILED, READ). This distinguishes it from sibling tools like UpdateConversationThread or SendConversationMessage, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only mentions a conditional parameter usage for FAILED messages, but does not set it apart from other update tools or specify scenarios where it should or should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, and the description's 'Fetch' aligns with read-only behavior. The description adds context about the type of information returned (status and configuration) but does not disclose error behavior, permission requirements, or other operational details beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and resource. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description covers the core purpose. However, the presence of a similarly named sibling ('RetrieveChannelAccountDetails') means the description should clarify the tool's specific scope, which it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter channel_account_id is fully documented in the schema (100% coverage). The description reiterates using the ID but adds no additional semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and identifies the resource ('specific HubSpot channel account') and the input ('using the channel account ID'). It mentions the kind of details ('status and configuration'). However, it doesn't differentiate from the sibling tool 'RetrieveChannelAccountDetails', which appears to serve a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'RetrieveChannelAccountDetails' or 'RetrieveChannelAccounts'. No prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the update action without mentioning side effects, mutability, reversibility, auth requirements, or any other behavioral traits. This is a significant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource, and contains no filler or redundant information. It efficiently captures the essence of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the basic purpose and context, it lacks usage guidelines and behavioral transparency. Given the existence of similar sibling tools and the absence of annotations/output schema, the description is only minimally complete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context by mentioning 'account name' and 'delivery identifier', which maps to the schema parameters, but does not add detail beyond what the schema already provides. The staging token context slightly aids understanding but is not a major addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update the account name and delivery identifier') and the resource ('channel account staging token'), with the context of 'public app connection flow' that distinguishes it from sibling tools like UpdateChannelAccountInfo. It is a specific verb+resource statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (staging token, public app connection flow) but does not explicitly state when to use this tool versus alternatives like UpdateChannelAccountInfo. No exclusions or alternative guidance are provided, so the usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true, so the read-only nature is covered. The description adds no additional behavioral context such as return format, pagination, error handling, or permissions. Since the annotation covers the main safety aspect, the description is acceptable but does not go beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of 12 words, with the key action ('Retrieve detailed information') front-loaded. There is no redundancy, filler, or repetition of the title. Every word contributes to the meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one required parameter and no output schema, the description is largely sufficient. It identifies the resource and the parameter. The phrase 'detailed information' is somewhat vague in terms of what fields will be returned, but given the low complexity and existing annotations, the description provides adequate context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter inbox_id ('The unique identifier for the conversation inbox you wish to retrieve details for'). With 100% schema description coverage, the description does not need to add parameter detail. It adds no extra semantics beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Retrieve detailed information about a specific conversation inbox by its ID.' It specifies a concrete verb ('Retrieve') and resource ('conversation inbox'), and the phrase 'by its ID' aligns with the required parameter. It does not explicitly differentiate from sibling tools like ListConversationInboxes, but the word 'specific' conveys single-item retrieval, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you have an inbox ID and need detailed information—but it does not provide explicit guidance on when to use it versus alternatives (e.g., ListConversationInboxes for enumeration). No exclusions or alternative tool references are mentioned, so usage context is only implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a safe read operation, and the description is consistent with that. However, the description adds no additional behavioral context such as specific data returned, pagination, or permissions, so it merely meets the baseline without exceeding it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It front-loads the primary action and resource, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema) and the read-only annotation, the description is largely sufficient. It could be improved by specifying what types of details are included, but it is not critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for channel_id. The tool description does not add any additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves comprehensive details about a specific channel using a channel ID. It is specific about the verb and resource, but does not explicitly distinguish itself from sibling tools like RetrieveChannelAccounts or GetChannelAccountDetails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a channel ID and need details, but it does not provide explicit guidance on when to prefer this over alternatives or when not to use it. No exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core behavior: updating status and archiving/restoring threads, including specific boolean semantics. However, with no annotations provided, the description carries the full burden but does not mention potential side effects, permissions, reversibility beyond 'restore', or error conditions. It adds minimal context beyond what the title and schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, directly front-loaded with the primary purpose, and uses precise language. Every sentence contributes useful information without unnecessary elaboration. It is exceptionally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 3 parameters and full schema coverage. The description adequately explains the main actions and boolean usage. However, the absence of annotations and output schema means the description does not cover return values or error conditions, and it does not distinguish from the ArchiveConversationThread sibling. For a simple update tool, this is mostly complete but could be improved with additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for all three parameters, with descriptions for each. The tool description repeats the boolean semantics in the schema ('Set to true to archive or false to restore') but adds no new meaning about parameter interactions or constraints. Since schema coverage is high, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool updates a single conversation thread's status (OPEN/CLOSED) or archives/restores it. It identifies a specific verb (update) and resource (single conversation thread), making the purpose clear. However, it does not explicitly differentiate from sibling tools like ArchiveConversationThread, which likely overlaps with the archive/restore functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to change a thread's status or archive/restore it) but provides no explicit guidance on alternatives or exclusions. There is no mention of using ArchiveConversationThread for archive-only operations or any context about choosing this tool over others. The usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a safe read operation. The description adds context about the returned fields (channel, inbox ID, delivery identifiers) but does not disclose the full response shape, pagination, or error behavior. It provides some value beyond the annotation but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, directly states the action, and includes the key metadata fields. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must convey return behavior. It lists some returned fields but uses 'including,' which suggests a non-exhaustive list. It also lacks any mention of error scenarios or edge cases, leaving some ambiguity for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add any new parameter semantics beyond that, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieve' and clearly identifies the resource as 'detailed metadata about a channel account on a custom channel.' It also lists the specific metadata fields included (channel, inbox ID, delivery identifiers), which helps distinguish it from the sibling tool GetChannelAccountDetails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description: this tool is for retrieving details of a custom channel account. However, there is no explicit when-to-use guidance or mention of alternatives, and the sibling GetChannelAccountDetails could overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the required OAuth scope ('conversations.custom_channels.write') and hints at the behavior of using different delivery identifiers. However, it does not describe side effects, return values, or any restrictions beyond the scope, leaving some behavioral aspects opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant wording. The first sentence states the core action, and the second adds value by explaining the use case and required scope. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (6 parameters, no output schema), the description covers the essential context: purpose, scope, and conceptual usage. It could be more complete by explicitly noting that the inbox and channel must already exist or by describing the response, but the core information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds some context about delivery identifiers that helps interpret delivery_identifier_type/value, but it does not provide additional meaning beyond what the schema already describes for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new account') and the resource ('within a specific custom communication channel'). It also explains the purpose ('Enables multiple accounts to communicate over a single channel with different delivery identifiers'), which distinguishes it from update/retrieve siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when creating a channel account) and provides context about multiple accounts per channel, but it does not explicitly mention alternatives or when not to use it. There is no direct comparison to UpdateChannelAccountInfo or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read operation. The description adds minimal behavioral context beyond scope (specific message within a thread), but does not disclose return format or edge-case behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It communicates the core action, resource, and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with full parameter documentation and a read-only annotation, the description is sufficiently complete. It lacks return-value details but that is not critical given the straightforward nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description only reiterates that a message ID is used without adding extra semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a specific message within a conversation thread using a message ID. It distinguishes from sibling tools like RetrieveThreadById (which retrieves the thread itself) and GetMessageHistoryForThread (which lists messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this when you need details for a specific message by ID. However, it does not explicitly mention when to prefer this over RetrieveFullMessageContent or other alternatives, nor does it state exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose the important side-effect that setting set_authorization_status to false disables the account. However, it omits other behavioral details such as required permissions, reversibility, or the effect of updating only one field.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the action, the target resource, and a key behavioral example, all in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple four-parameter mutation tool with no output schema and no annotations, the description sufficiently covers the tool's purpose and key behavior. It could add more about return values or explicitly differentiate from UpdateChannelAccountStaging, but overall it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 little beyond the schema: 'name and/or authorization status' maps to the existing optional parameters, and the disabling note is already present in the schema description for set_authorization_status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update', identifies the resource as 'channel account', and scopes it to 'custom channel', which clearly distinguishes it from sibling tools like CreateChannelAccount, GetChannelAccountDetails, and UpdateChannelAccountStaging.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what can be updated (name and/or authorization status) and how to disable the account, but it does not explicitly contrast this tool with alternatives like UpdateChannelAccountStaging or provide exclusions. Hence it gives clear context but no direct selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, matching the read-only description, so no contradiction. The description adds conceptual background and filter/sort capabilities, but does not disclose pagination behavior, default filters (e.g., non-archived only), or response format. With no output schema, more behavioral detail would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and includes a useful definition parenthetical. Every sentence earns its place with no unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 optional parameters and no output schema, the description could more thoroughly explain pagination, default behavior, and return value structure. It covers the core purpose but leaves behavioral details to the schema, which only partially compensates for the missing output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameters are self-describing. The description only generically mentions 'optional filters and sorting' without detailing any parameters. As per baseline for high schema coverage, a score of 3 is appropriate; description adds no significant semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves a list of channel accounts and defines what a channel account is, distinguishing it from single-entity tools like RetrieveChannelAccountDetails. The verb 'Retrieve' combined with 'list' makes the scope explicit, and the example clarifies the concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for listing and filtering channel accounts, with optional filters and sorting. It provides clear context though it does not explicitly mention alternatives or exclusions. The 'list' wording differentiates it from single-account retrieval tools, but no direct comparison is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-safe nature is covered. The description adds the association context but does not disclose pagination behavior, rate limits, or error handling beyond what the schema already provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear sentence, front-loaded with the verb, and no redundant words. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-fetch tool, the description covers the core purpose. The pagination parameters (after, limit) imply a paged response, but the description doesn't explicitly state the return envelope. Given the annotations and schema, this is nearly complete, with a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 3 parameters with descriptions (100% coverage), so the baseline is 3. The tool description primarily restates the custom_channel_id purpose without adding new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and identifies both the resource ('list of accounts') and the scope ('specific custom channel, identified by channel ID'). This clearly distinguishes it from siblings like RetrieveChannelAccounts, which likely target non-custom channels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for fetching accounts for a specific custom channel by ID, giving clear context on when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description adds behavioral context by listing exactly what detail categories are returned (message content, sender info, timestamps), which is useful since no output schema is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, target, and key returned details without any wasted words or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two required parameters and no output schema, the description adequately covers purpose and expected return fields. The only minor gap is the lack of explicit usage guidance relative to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both channel_id and message_id are already well-documented in the schema. The description adds no additional parameter syntax or constraints beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (Get), the resource (details of a specific message sent through a custom channel), and the scope (message content, sender information, timestamps), distinguishing it from general message history tools like GetMessageHistoryForThread or RetrieveFullMessageContent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when retrieving details of a specific custom-channel message but does not explicitly contrast it with sibling tools such as RetrieveFullMessageContent or RetrieveThreadMessage, nor does it provide when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description aligns with a read operation ('Fetch'). It adds minimal behavioral context beyond that, such as the scope of inboxes and the existence of filters/sorting, but does not disclose pagination details or response structure. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and every word adds value. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 4 optional parameters (fully documented in schema), no required parameters, and readOnlyHint annotation, the description adequately conveys the tool's purpose and scope. It could mention response pagination, but the schema covers the 'after' cursor, so the information is available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with clear descriptions (sort, after, limit, is_archived). The description's mention of 'optional filters and sorting' reinforces these but adds no extra semantic detail. Baseline of 3 applies since schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource as 'conversation inboxes (shared inboxes and help desks)' with optional filters and sorting. This distinguishes it from sibling tools like GetInboxDetails (getting a single inbox) and ListConversationChannels (listing channels).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for listing conversation inboxes and customizing results with filters/sorting, implying its use for enumeration tasks. It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to infer when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the read-only behavior is already known. The description adds the batch-call behavior and the fact that it returns participant info, but does not disclose additional traits such as error handling or partial result behavior. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the action, object, and purpose without redundancy. It is front-loaded with the key information and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 sufficiently covers purpose and usage. It mentions 'detailed participant information' as the return concept. It could have added a note about unresolved IDs or response format, but given the simplicity and read-only annotation, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the only parameter (actor_ids) with a clear description and example ('['A-12345', 'V-67890']'), achieving 100% schema coverage. The tool description adds minimal extra meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resolve') with a clear resource ('a list of ActorIds') and outcome ('detailed participant information'). It distinguishes itself from sibling tools by emphasizing the batch aspect and the conversation participant context, making it clear this is different from single-actor lookups like RetrieveActorDetails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use it: 'use this to understand who the participants in a conversation are.' It also implies batch use ('in one batch call'), which guides the agent to choose this over single-actor resolve tools. It does not explicitly name alternatives or exclusions, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is already provided, and the description adds pagination behavior (pass `after` from paging.next.after), which is useful. There is no contradiction with annotations, and the read-only nature means no destructive side effects need to be disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, then adding filter and pagination details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema, the description provides a solid overview including filters, sorting, and pagination. It mentions the response's paging structure, but does not specify the overall return format or defaults, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description groups filters by category (inbox, status, associated contact/ticket, time window) and mentions sorting, but does not add details beyond what is already in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves conversation threads from HubSpot Conversations with a specific verb and resource. It outlines filtering and sorting capabilities, distinguishing it as a list/filter tool, but does not explicitly contrast it with sibling tools like RetrieveThreadById.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool to retrieve conversation threads with optional filters and sorting. It does not explicitly mention alternatives or exclusions, but the plural 'threads' and filter options imply it is for listing rather than single-thread retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already include readOnlyHint=true, so the read-only nature is known. The description adds the ID prefix scheme, but no additional behavioral details such as return format, error cases, or rate limits. This is acceptable for a simple read operation, but not exceptional beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences: the first states the primary purpose and input, and the second adds essential context about actor ID prefixes. It is front-loaded, concise, and every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and a readOnlyHint annotation, but no output schema. The description explains the input well but does not specify what 'details' includes or what the response structure looks like, leaving a notable gap for an AI agent that needs to understand the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes actor_id as a string with a generic example, but the description adds meaningful semantics by explaining the prefix types ('A-', 'V-', 'B-', 'E-', 'S-', 'I-'). This helps the agent construct and validate IDs, going beyond the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieve' and identifies the resource as 'details of a specific actor (conversation participant)' using an actor ID. It also explains the ID prefix conventions, clearly distinguishing it from sibling tools like ResolveConversationActors or channel account retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for fetching a single actor's details when the actor ID is known, as indicated by 'by actor ID'. It provides context with the ID prefix breakdown, but it does not explicitly contrast with alternatives or state exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true in the annotations, the non-mutating nature is already declared. The description adds that the tool returns original text and rich text and addresses truncation, but it does not elaborate on the response format, content structure, or error behavior, leaving the description to carry only partial behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately states the action and resource, then follows with a concise trigger condition. Every word contributes to the meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (two string parameters, read-only annotation, no output schema), the description sufficiently covers purpose, usage context, and return content. Combined with the fully documented schema and annotations, an agent has all needed information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with clear descriptions for message_id and conversation_thread_id, achieving 100% coverage. The tool description adds no parameter-specific meaning, so the baseline of 3 is appropriate as no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the original text and rich text of a message, with the specific qualifier of providing full untruncated content. This distinguishes it from sibling retrieval tools by emphasizing the 'full original' content and the truncation context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says it is useful when the message's truncationStatus indicates it might be truncated, giving clear when-to-use guidance. It does not name alternative tools or provide when-not guidance, but the use case is directly and appropriately contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds valuable behavioral context: it specifies pagination via the `after` cursor and discloses that the result includes system events like assignments and status changes. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and every word adds value. The pagination hint is concise and directly actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description compensates by listing the types of entries included (messages, comments, system events) and explaining pagination. Given the moderate complexity, this is sufficient for an AI agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 reinforces the `after` cursor usage but does not add new meaning beyond what the schema already documents for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Retrieve the message history for a given conversation thread by its ID.' It enumerates content types (messages, comments, system events), distinguishing it from sibling tools like RetrieveThreadMessage (single message) or RetrieveThreadById (thread metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool (when full thread history is needed) and provides pagination instructions. It does not explicitly name alternatives or exclusions, but the context is clear and the sibling list reinforces the distinction from single-message retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the tool's read-only nature is already conveyed. The description adds context by listing the specific information returned, which helps the agent anticipate the response contents. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, resource, and key return fields without any redundant or filler text. Every word contributes to the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the responsibility of indicating return content. It lists several key fields (status, inbox, original channel, assignee, contact) which convey the nature of the response; while not exhaustive, it is adequate for a simple get-by-id tool with three documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters, including the required conversation_thread_id and optional booleans is_archived and include_ticket_association. The description does not add any parameter-specific semantics beyond the schema, so a baseline score of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Retrieve' and clearly identifies the resource and scope ('conversation thread by ID') while enumerating the detail fields (status, inbox, original channel, assignee, contact). This distinguishes it from sibling tools like RetrieveConversationThreads (list) and UpdateConversationThread (mutate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when a single thread's details are needed by ID, and the context is unambiguous. However, it does not explicitly mention when not to use this tool or name alternative tools for related tasks like getting message history or updating threads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only an openWorldHint annotation (which gives no safety/behavior info), the description carries the burden of behavioral disclosure. It explains important fallback behavior: missing channel_id/channel_account_id are taken from the thread, missing recipients are derived from the latest incoming message, and sender_actor_id defaults to HUBSPOT_DEFAULT_SENDER_ACTOR_ID. It also spells out field precedence and the mode='get_request_schema' capability, which goes well beyond the schema. It doesn't mention side effects or permissions, but for a message-sending tool this is substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured, front-loading the core purpose in the first clause. It is a few long sentences, but each clause carries unique information about delivery, internal notes, request_body, fallbacks, and schema inspection. A bit of trimming could improve readability, but it's not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no output schema and minimal annotations, the description is highly complete. It explains the central execution flow, alternative invocation modes, parameter precedence, and default behaviors. It doesn't describe the return value, but the absence of an output schema is offset by the detailed operational guidance. It could be more explicit about what happens after a message is sent, but overall it is sufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics beyond the schema: 'typed fields win on conflict' between typed fields and request_body, and it clarifies default derivation for channel_id, channel_account_id, recipients, and sender_actor_id. This helps the agent understand how parameters interact and what will happen if they are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Send a new message on an existing conversation thread — delivered to the customer on the thread's channel.' It names the resource (conversation thread), the action (send), and distinguishes it from sibling tools like RetrieveThreadMessage or UpdateConversationThread. It also adds nuance by explaining that message_type=COMMENT is for internal notes, making the purpose even more precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives solid context for when to use the tool: 'on an existing conversation thread' and 'delivered to the customer.' It also clarifies a key decision point with 'set message_type=COMMENT for an internal note instead.' However, it does not explicitly name sibling alternatives or provide when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse openWorldHint annotation, it discloses that typed fields win over request_body on conflict, request_body must be stringified JSON, and that channelAccountId, senders, and recipients are de facto required even though the schema only lists custom_channel_id as required. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. Front-loads the core action, then adds mode and requirement guidance; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter tool with no output schema, the description captures purpose, mode, body alternatives, requirements, and how to inspect the full schema. However, it does not qualify the required-fields statement by mode and does not describe return behavior, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 14 parameters (100%), so baseline is 3. The description adds meaningful semantics: the typed-fields-vs-request_body priority, the mode's schema-inspection purpose, and execute-time required fields. This exceeds schema alone but leaves detailed field semantics to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Publish a message over a specified custom channel into HubSpot Conversations' and clearly scopes it to custom-integrated messaging channels syncing external messages. This differentiates it from sibling tools like SendConversationMessage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear use-case context ('custom-integrated messaging channels to sync external messages into HubSpot') and operational guidance (typed fields vs request_body, mode='get_request_schema' to inspect schema). Does not explicitly name when-not-to-use alternatives, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail beyond the destructiveHint annotation by disclosing that the thread is permanently deleted after 30 days. This informs the agent about the irreversible nature and lifecycle.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The action is front-loaded and the additional detail about 30-day deletion is concise and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with destructiveHint, the description is sufficient. It covers the purpose, the deletion timeline, and there is no output schema to explain. The context is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for thread_identifier. The tool description adds no additional parameter semantics, but the schema already fully documents the parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'archive' and the resource 'conversation thread', and adds 'marking it for deletion' to clarify the action. This distinguishes it from siblings like UpdateConversationThread or RetrieveThreadById.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context (archiving marks for deletion) and the 30-day retention implies a specific use case. However, it does not explicitly name alternatives or exclusion scenarios, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![hubspot-conversations-mcp MCP server](https://glama.ai/mcp/servers/amalodev/hubspot-conversations-mcp/badges/card.svg)](https://glama.ai/mcp/servers/amalodev/hubspot-conversations-mcp)

Score Badge

Copy to your README.md:

[![hubspot-conversations-mcp MCP server](https://glama.ai/mcp/servers/amalodev/hubspot-conversations-mcp/badges/score.svg)](https://glama.ai/mcp/servers/amalodev/hubspot-conversations-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/amalodev/hubspot-conversations-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server