HubSpot MCP Server
Provides comprehensive access to HubSpot's CRM API, enabling management of CRM objects (companies, contacts, deals, leads), engagement tracking (calls, emails, meetings, notes, tasks), product management, associations between objects, and communication preferences with support for batch operations and advanced search capabilities.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HubSpot MCP Serversearch for contacts in San Francisco with email containing '@acme.com'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server implementation for the HubSpot API, providing a standardized interface for accessing and managing CRM data.
Features
Complete coverage of the HubSpot CRM API
Support for all standard CRM objects (companies, contacts, deals, etc.)
Advanced association management with CRM Associations v4
Company-specific endpoints with property validation
Batch operations for efficient data management
Advanced search and filtering capabilities
Type-safe parameter validation with Zod
Prerequisites
If you don't have an API key, follow the steps here to obtain an access token. OAuth support is planned as a future enhancement.
Client Configuration
There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx or build from source. Each of these options is explained below.
Smithery Remote Server (Recommended)
To add a remote server to your MCP client config.json, run the following command from Smithery CLI:
npx -y @smithery/cli install @Koozow/hubspot-mcpEnter your HUBSPOT_ACCESS_TOKEN when prompted.
Smithery SDK
If you are developing your own agent application, you can use the boilerplate code here.
NPX Local Install
To install the server locally with npx, add the following to your MCP client config.json:
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": [
"@shinzolabs/hubspot-mcp"
],
"env": {
"HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
}
}
}
}Build from Source
Download the repo:
git clone https://github.com/shinzo-labs/hubspot-mcp.gitInstall packages (inside cloned repo):
pnpm iAdd the following to your MCP client
config.json:
{
"mcpServers": {
"hubspot": {
"command": "node",
"args": [
"/path/to/hubspot-mcp/index.js"
],
"env": {
"HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
}
}
}
}Config Variables
Variable | Description | Required? | Default |
| Access Token for Hubspot Application | Yes | |
| Port for Streamable HTTP transport method | No |
|
| Enable telemetry | No |
|
Supported Tools
Core CRM Objects
crm_list_objects: List CRM objects with optional filtering and paginationcrm_get_object: Get a single CRM object by IDcrm_create_object: Create a new CRM objectcrm_update_object: Update an existing CRM objectcrm_archive_object: Archive (delete) a CRM objectcrm_search_objects: Search CRM objects using advanced filterscrm_batch_create_objects: Create multiple objects in a single requestcrm_batch_read_objects: Read multipl objects in a single requestcrm_batch_update_objects: Update multiple objects in a single requestcrm_batch_archive_objects: Archive (delete) multiple objects in a single request
Companies
crm_create_company: Create a new company with validated propertiescrm_update_company: Update an existing companycrm_get_company: Get a single company by IDcrm_search_companies: Search companies with specific filterscrm_batch_create_companies: Create multiple companies in a single requestcrm_batch_update_companies: Update multiple companies in a single requestcrm_get_company_properties: Get all available company propertiescrm_create_company_property: Create a new company property
Contacts
crm_create_contact: Create a new contact with validated propertiescrm_update_contact: Update an existing contact's informationcrm_get_contact: Get a single contact by IDcrm_search_contacts: Search contacts with specific filterscrm_batch_create_contacts: Create multiple contacts in a single requestcrm_batch_update_contacts: Update multiple contacts in a single requestcrm_get_contact_properties: Get all available contact propertiescrm_create_contact_property: Create a new contact property
Leads
crm_create_lead: Create a new lead with validated propertiescrm_update_lead: Update an existing lead's informationcrm_get_lead: Get a single lead by IDcrm_search_leads: Search leads with specific filterscrm_batch_create_leads: Create multiple leads in a single requestcrm_batch_update_leads: Update multiple leads in a single requestcrm_get_lead_properties: Get all available lead propertiescrm_create_lead_property: Create a new lead property
Engagement Management
engagement_details_get: Get details of a specific engagementengagement_details_create: Create a new engagementengagement_details_update: Update an existing engagementengagement_details_archive: Archive (delete) an engagementengagement_details_list: List all engagements with filteringengagement_details_get_associated: Get associated engagements
Calls
calls_create: Create a new call recordcalls_get: Get call detailscalls_update: Update a call recordcalls_archive: Archive a callcalls_list: List all callscalls_search: Search callscalls_batch_create: Create multiple callscalls_batch_read: Read multiple callscalls_batch_update: Update multiple callscalls_batch_archive: Archive multiple calls
Emails
emails_create: Create a new email recordemails_get: Get email detailsemails_update: Update an emailemails_archive: Archive an emailemails_list: List all emailsemails_search: Search emailsemails_batch_create: Create multiple emailsemails_batch_read: Read multiple emailsemails_batch_update: Update multiple emailsemails_batch_archive: Archive multiple emails
Meetings
meetings_create: Create a new meetingmeetings_get: Get meeting detailsmeetings_update: Update a meetingmeetings_archive: Archive (delete) a meetingmeetings_list: List all meetingsmeetings_search: Search meetingsmeetings_batch_create: Create multiple meetingsmeetings_batch_update: Update multiple meetingsmeetings_batch_archive: Archive multiple meetings
Notes
notes_create: Create a new notenotes_get: Get note detailsnotes_update: Update a notenotes_archive: Archive a notenotes_list: List all notesnotes_search: Search notesnotes_batch_create: Create multiple notesnotes_batch_read: Read multiple notesnotes_batch_update: Update multiple notesnotes_batch_archive: Archive multiple notes
Tasks
tasks_create: Create a new tasktasks_get: Get task detailstasks_update: Update a tasktasks_archive: Archive a tasktasks_list: List all taskstasks_search: Search taskstasks_batch_create: Create multiple taskstasks_batch_read: Read multiple taskstasks_batch_update: Update multiple taskstasks_batch_archive: Archive multiple tasks
Associations and Relationships
crm_list_association_types: List available association typescrm_get_associations: Get all associations between objectscrm_create_association: Create an associationcrm_archive_association: Archive (delete) an associationcrm_batch_create_associations: Create multiple associationscrm_batch_archive_associations: Archive (delete) multiple associations
Communication Preferences
communications_get_preferences: Get contact preferencescommunications_update_preferences: Update contact preferencescommunications_unsubscribe_contact: Global unsubscribecommunications_subscribe_contact: Global subscribecommunications_get_subscription_definitions: Get subscription definitionscommunications_get_subscription_status: Get status for multiple contactscommunications_update_subscription_status: Update status for multiple contacts
Products
products_create: Create a product with the given properties and return a copy of the object, including the ID.products_read: Read an Object identified by IDproducts_update: Perform a partial update of an Object identified by ID. Read-only and non-existent properties will result in an error. Properties values can be cleared by passing an empty string.products_archive: Move an Object identified by ID to the recycling bin.products_list: Read a page of products. Control what is returned via thepropertiesquery param.afteris the paging cursor token of the last successfully read resource will be returned as thepaging.next.afterJSON property of a paged response containing more results.products_search: Search productsproducts_batch_create: Create a batch of productsproducts_batch_read: Read a batch of products by internal ID, or unique property values. Retrieve records by theidPropertyparameter to retrieve records by a custom unique value property.products_batch_update: Update a batch of products by internal ID, or unique values specified by theidPropertyquery param.products_batch_archive: Archive a batch of products by ID
Contributing
Contributions are welcomed and encouraged! Please read CONTRIBUTING.md for guidelines on issues, contributions, and contact information.
Data Collection and Privacy
Shinzo Labs collects limited anonymous telemetry from this server to help improve our products and services. No personally identifiable information is collected as part of this process. Please review the Privacy Policy for more details on the types of data collected and how to opt-out of this telemetry.
License
MIT
Available Tools
112 toolscalls_archiveC
Archive (delete) a call record
| Name | Required | Description | Default |
|---|---|---|---|
| callId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates this is a destructive operation ('delete'), which is critical, but doesn't mention permanence, permissions needed, recovery options, or what happens to associated data. For a destructive tool with zero annotation coverage, this is insufficient.
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 (4 words) and front-loaded with the essential action. Every word earns its place, with no wasted text or unnecessary elaboration.
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 destructive operation with no annotations, no output schema, and 0% parameter documentation, the description is inadequate. It should explain more about the consequences of archiving/deleting, what 'callId' represents, and what (if anything) is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't mention the 'callId' parameter at all, and with 0% schema description coverage, the parameter is undocumented. However, since there's only one required parameter, the baseline is higher. The description doesn't add value beyond the obvious implication that 'callId' identifies the call to archive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and resource ('a call record'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'calls_batch_archive' or 'calls_update', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'calls_batch_archive' for multiple calls or 'calls_update' for modifications. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_batch_archiveC
Archive (delete) multiple call records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| callIds | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool archives (deletes) multiple call records, indicating a destructive mutation, but lacks details on permissions, reversibility, error handling, or rate limits. This is a significant gap for a destructive 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 a single, efficient sentence that front-loads the key action and scope. There is no wasted verbiage, making it highly concise and well-structured for quick understanding.
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 destructive batch tool with no annotations, 0% schema description coverage, and no output schema, the description is inadequate. It lacks critical behavioral details like safety warnings, response format, or error conditions, leaving the agent under-informed for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description implies the parameter 'callIds' is an array of call records to archive. However, it doesn't specify format, constraints, or maximum batch size. With one parameter and no schema descriptions, the description adds minimal value beyond the schema's structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('archive (delete)') and resource ('multiple call records') with the scope 'in a single request.' It distinguishes from the singular 'calls_archive' sibling by specifying batch operation, though it doesn't explicitly contrast with other batch operations like 'calls_batch_create' or 'calls_batch_update.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'calls_archive' for single deletions or other batch operations. The description implies batch deletion but doesn't mention prerequisites, constraints, or comparative use cases with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_batch_createC
Create multiple call records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a creation operation but doesn't mention permissions required, whether it's idempotent, rate limits, error handling for partial failures, or what the response looks like. This is inadequate for a batch mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately front-loaded with the core functionality.
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 complex nested parameters (9+ properties plus associations), no annotations, and no output schema, the description is severely incomplete. It doesn't explain the data model, required fields beyond schema, success/failure behavior, or practical usage patterns.
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 0%, so the description must compensate but provides no parameter information. The complex nested schema with 9+ properties and associations is completely undocumented in the description, leaving the agent to infer usage from schema structure alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple call records') and the method ('in a single request'), which is specific and distinguishes it from the singular 'calls_create' sibling. However, it doesn't explicitly differentiate from other batch operations like 'calls_batch_update' or 'calls_batch_archive' beyond the verb 'create'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'calls_create' for single records or other batch operations. The description only states what it does, not when it's appropriate or what prerequisites might exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_batch_readC
Read multiple call records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
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 states this is a read operation, implying it's non-destructive, but doesn't cover critical aspects like authentication requirements, rate limits, error handling, response format, or whether it's idempotent. The description adds minimal value beyond the basic operation type.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a tool with a clear primary function, though the brevity comes at the cost of completeness.
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 operation with complex nested parameters (1 parameter with 3 sub-properties), no annotations, and no output schema, the description is inadequate. It doesn't explain the parameter structure, return values, error conditions, or how this tool fits within the broader ecosystem of call-related operations, leaving significant gaps 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 schema description coverage is 0%, and the description provides no information about parameters. The input schema shows a complex nested structure with 'inputs' array containing objects with 'id', 'properties', and 'associations', but the description doesn't explain what these mean, their formats, or how they affect the batch read operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Read') and resource ('multiple call records') with the specific capability of batch processing ('in a single request'). It distinguishes from individual read operations like 'calls_get' but doesn't explicitly differentiate from other batch operations like 'calls_batch_archive' or 'calls_batch_update' beyond the 'Read' verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention when batch reading is preferable to individual 'calls_get' calls, nor does it address prerequisites, performance considerations, or limitations compared to other batch operations like 'calls_batch_read' versus 'calls_list' or 'calls_search'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_batch_updateC
Update multiple call records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only mentions it's an update operation. It doesn't disclose behavioral traits like whether this is idempotent, what permissions are required, how errors are handled in batch, rate limits, or what the response contains. For a batch mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality. There's zero wasted verbiage, making it 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 this is a batch mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't address critical context like error handling, response format, or limitations, leaving the agent with insufficient information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but provides no parameter information. It doesn't explain the 'inputs' array structure, the required 'id' and 'properties' fields, or the specific call properties that can be updated. The description adds no meaning beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('multiple call records'), and specifies the scope ('in a single request'). It distinguishes from the singular 'calls_update' tool by emphasizing batch processing, though it doesn't explicitly mention this sibling difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'calls_update' (for single updates) or other batch operations. The description only states what it does, not when it's appropriate or what prerequisites might exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_createC
Create a new call record
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create a new call record' implies a write/mutation operation but provides no information about permissions required, whether the operation is idempotent, what happens on failure, rate limits, or what the response contains. This leaves significant behavioral questions unanswered for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words, with zero wasted language. It's front-loaded with the core action and resource. While this conciseness comes at the cost of completeness, the structure itself is optimal for what little information is provided.
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 complex nested parameters (2 parameters with deep nesting), 0% schema description coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain the parameter structure, required fields, behavioral constraints, or what to expect upon success/failure, leaving the agent with insufficient context to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 2 parameters (one required), the description provides no information about parameters. The schema shows complex nested objects with many properties, but the description doesn't explain what 'properties' or 'associations' mean in this context, nor does it mention required fields like 'hs_call_body' and 'hs_call_title'.
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 'Create a new call record' clearly states the verb ('Create') and resource ('call record'), making the basic purpose understandable. However, it doesn't differentiate this tool from sibling tools like 'calls_batch_create' or other create tools in the system, leaving ambiguity about when to use this specific single-create versus batch alternatives.
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 'calls_batch_create' available, there's no indication whether this is for single-record creation versus batch operations, nor any prerequisites or context for when this specific tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_getC
Get details of a specific call
| Name | Required | Description | Default |
|---|---|---|---|
| callId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it 'gets details' without disclosing behavioral traits like authentication needs, rate limits, error handling, or what 'details' include. It lacks context on whether this is a read-only operation or has side effects, which is critical for a tool with no structured safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place, making it appropriately sized for a basic tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no schema descriptions, no annotations, no output schema), the description is incomplete. It doesn't address parameter meanings, behavioral context, or output expectations, leaving the agent with insufficient information to use the tool effectively beyond its basic intent.
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 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'callId' represents, what 'properties' or 'associations' arrays do, or how they affect the output. With 3 parameters undocumented, this is a significant gap beyond the minimal baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific call' clearly states the verb ('Get') and resource ('call'), making the purpose understandable. However, it doesn't distinguish this tool from sibling tools like 'calls_list' or 'calls_search' that also retrieve call information, missing explicit 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?
No guidance is provided on when to use this tool versus alternatives like 'calls_list' for multiple calls or 'calls_search' for filtered searches. The description implies usage for a single call but doesn't specify prerequisites or exclusions, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_listC
List all calls with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| after | No | ||
| properties | No | ||
| associations | No | ||
| archived | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'List all calls' but doesn't mention pagination behavior (implied by 'limit' and 'after' parameters), rate limits, authentication requirements, or whether it's a read-only operation. The description is insufficient for a tool with 5 parameters and no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 6 words, front-loading the core purpose. There's zero wasted language, making it easy to parse quickly, though this conciseness comes at the expense of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, how filtering works, or behavioral characteristics. The agent would struggle to use this tool effectively based solely on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. 'optional filtering' is mentioned but doesn't map to specific parameters like 'limit', 'after', 'properties', 'associations', or 'archived'. The description fails to provide any meaningful parameter context beyond what's in the bare 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 'List all calls with optional filtering' clearly states the verb ('List') and resource ('calls'), but it's vague about what 'optional filtering' entails. It doesn't distinguish this tool from sibling tools like 'calls_search' or 'calls_get', leaving ambiguity about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'calls_search' or 'calls_get'. The description mentions 'optional filtering' but doesn't specify what types of filtering are available or how it differs from search functionality, leaving the agent without clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_searchD
Search calls with specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
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 but provides almost none. It doesn't indicate whether this is a read-only operation, what permissions might be required, whether it's paginated, what the response format might be, or any rate limits. For a search tool with complex filtering capabilities, this lack of behavioral information is a significant gap.
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 at just 5 words. While this brevity contributes to under-specification in other dimensions, as a standalone assessment of conciseness, it's maximally efficient with zero wasted words. The single sentence is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters with nested objects, 0% schema coverage, no output schema, no annotations), the description is completely inadequate. A search tool with complex filtering capabilities requires much more explanation about parameter usage, expected behaviors, and output format. The minimal description fails to provide the necessary context for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The tool description mentions 'specific filters' which only hints at the filterGroups parameter but doesn't explain any of the parameters' purposes, relationships, or usage. It doesn't mention properties, limit, after, or sorts parameters at all, leaving them completely undocumented.
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 'Search calls with specific filters' states the basic action but is vague about scope and differentiation. It doesn't specify what kind of search this is (e.g., full-text, filtered list, advanced query) or how it differs from sibling tools like calls_list or calls_get. The verb 'search' is generic and doesn't convey the specific functionality implied by the complex input schema.
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 multiple sibling tools like calls_list, calls_get, and other search tools (emails_search, meetings_search), there's no indication of when this specific calls_search tool is appropriate versus those other options. The description lacks any context about use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
calls_updateC
Update an existing call record
| Name | Required | Description | Default |
|---|---|---|---|
| callId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Update' implies a mutation operation, the description doesn't specify whether this requires specific permissions, what happens to fields not included in the update (partial vs. full replacement), whether changes are reversible, or any rate limits or side effects. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words, which is efficient for stating the basic purpose. However, this brevity comes at the cost of completeness—it's front-loaded but lacks necessary details. While not wasteful, it's arguably under-specified rather than optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, 0% schema description coverage, no output schema, and complex nested parameters, the description is inadequate. It doesn't explain the update behavior (partial/full), required permissions, error conditions, or return values. Given the context of sibling batch operations and rich parameter structure, more completeness is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the parameters have descriptions in the schema. The tool description mentions no parameters at all, failing to compensate for this gap. With 2 top-level parameters (callId and properties) and 9 nested properties under 'properties', the agent receives no semantic guidance about what these parameters represent or how to use them.
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 'Update an existing call record' clearly states the verb ('Update') and resource ('call record'), making the basic purpose understandable. However, it doesn't differentiate this tool from its sibling 'calls_batch_update' or other update tools in the server, leaving ambiguity about when to use this single-record update versus 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 no guidance on when to use this tool versus alternatives. With siblings like 'calls_batch_update' and 'calls_update' (presumably for single vs. batch operations), the agent receives no explicit or implied direction about choosing between them, nor any prerequisites or constraints for using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_get_preferencesC
Get communication preferences for a contact
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| subscriptionId | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a 'Get' operation, implying it's read-only, but doesn't clarify if it requires authentication, has rate limits, returns structured data, or handles errors. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by conveying essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain what 'communication preferences' entail, how results are returned, or error handling. For a tool with two parameters and no structured documentation, this leaves too much undefined for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no descriptions for the two parameters. The description mentions 'contact' but doesn't explain what 'contactId' or 'subscriptionId' represent, their formats, or if 'subscriptionId' is optional. It adds minimal value beyond the schema, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('communication preferences for a contact'), making the purpose unambiguous. However, it doesn't distinguish this tool from its sibling 'communications_get_subscription_status' or 'communications_get_subscription_definitions', which also retrieve communication-related data, so it falls short of a perfect score.
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 like 'communications_get_subscription_status' or 'communications_update_preferences'. It lacks context about prerequisites, such as whether the contact must exist or be subscribed, and offers no explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_get_subscription_definitionsC
Get all subscription definitions for the portal
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No |
TDQS
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 implies a read operation ('Get'), but lacks details on permissions, rate limits, pagination, or response format. For a tool with zero annotation coverage, this is insufficient, as it doesn't address how the tool behaves beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action without unnecessary words. It's appropriately sized for a simple tool, with zero waste or redundancy, making it easy to parse 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 lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It doesn't compensate for missing structured data by explaining return values, error conditions, or behavioral nuances, making it inadequate for a tool that might involve data retrieval in a communications context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter information beyond what the input schema provides. With 0% schema description coverage and one parameter ('archived'), the description fails to explain what 'archived' means (e.g., whether it filters for archived definitions) or its default behavior. This leaves the parameter undocumented and unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('all subscription definitions for the portal'), making the purpose specific and understandable. It distinguishes from siblings like 'communications_get_subscription_status' by focusing on definitions rather than status, though it doesn't explicitly contrast with other communications tools like 'communications_get_preferences'.
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. It doesn't mention prerequisites, context, or exclusions, such as whether it should be used before subscribing contacts or how it relates to other communications tools. This leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_get_subscription_statusC
Get subscription status for multiple contacts
| Name | Required | Description | Default |
|---|---|---|---|
| subscriptionId | Yes | ||
| contactIds | Yes |
TDQS
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 states it's a 'Get' operation, implying read-only behavior, but doesn't confirm if it's safe, whether it requires authentication, what happens with invalid inputs, or if there are rate limits. For a tool with zero annotation coverage, this minimal description leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the key information. There's zero waste 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 tool's moderate complexity (2 required parameters), lack of annotations, and no output schema, the description is insufficient. It doesn't explain what the returned status information includes, how errors are handled, or provide any context about the subscription system. For a tool with no structured behavioral or output documentation, this brief description leaves too many gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It mentions 'subscription status for multiple contacts', which hints at the purpose of 'subscriptionId' and 'contactIds' parameters, but doesn't explain what these IDs represent, their format, or constraints. This adds minimal semantic value beyond what's implied by the tool name, failing to adequately document the two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get subscription status') and target ('for multiple contacts'), which is specific and unambiguous. It distinguishes itself from sibling tools like 'communications_get_preferences' or 'communications_get_subscription_definitions' by focusing on status retrieval rather than definitions or preferences. However, it doesn't explicitly differentiate from other 'get' operations in the communications domain, keeping it at a 4 rather than a 5.
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. It doesn't mention when this tool is appropriate compared to other communications tools like 'communications_update_subscription_status' or 'communications_subscribe_contact', nor does it specify prerequisites or exclusions. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_subscribe_contactC
Subscribe a contact to all email communications
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| portalSubscriptionLegalBasis | No | ||
| portalSubscriptionLegalBasisExplanation | No |
TDQS
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 states the action ('Subscribe') which implies a write/mutation operation, but doesn't mention any behavioral traits like permission requirements, whether this is reversible (though 'communications_unsubscribe_contact' exists as a sibling), rate limits, or what happens on success/failure. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that states exactly what the tool does without any unnecessary words. It's perfectly front-loaded with the core functionality and wastes no space on redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 3 parameters (including complex legal basis parameters with enums), 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain the legal basis parameters, doesn't mention behavioral aspects like permissions or side effects, and doesn't clarify the relationship with sibling subscription tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 3 parameters are documented in the schema. The description mentions 'contact' which loosely relates to 'contactId', but provides no information about the two legal basis parameters or their significance. This fails to compensate for the complete lack of schema 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 clearly states the action ('Subscribe') and resource ('a contact to all email communications'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'communications_update_preferences' or 'communications_update_subscription_status', which might handle similar subscription-related 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 no guidance on when to use this tool versus alternatives. There are multiple sibling tools related to communications and subscriptions (e.g., 'communications_update_preferences', 'communications_update_subscription_status'), but the description doesn't explain how this tool differs or when it should be preferred over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_unsubscribe_contactC
Unsubscribe a contact from all email communications
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| portalSubscriptionLegalBasis | No | ||
| portalSubscriptionLegalBasisExplanation | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Unsubscribe' implies a write/mutation operation, the description doesn't address important behavioral aspects: whether this action is reversible, what permissions are required, whether it affects historical communications, what confirmation or response to expect, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for the core functionality and follows good front-loading principles by stating the primary action immediately.
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 3 parameters (including complex enum-based parameters), no annotations, and no output schema, the description is inadequate. It covers the basic purpose but fails to address parameter meanings, behavioral implications, usage context, or expected outcomes. The agent would struggle to use this tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for all 3 parameters, the description provides no information about what 'contactId', 'portalSubscriptionLegalBasis', or 'portalSubscriptionLegalBasisExplanation' mean or how they should be used. The description doesn't mention any parameters at all, leaving the agent to guess about the legal basis parameters' purpose and relationship to the unsubscribe action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Unsubscribe') and resource ('a contact from all email communications'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'communications_update_subscription_status', but the specificity of 'all email communications' provides some distinction from more granular subscription management 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 no guidance on when to use this tool versus alternatives like 'communications_update_subscription_status' or 'communications_update_preferences'. It doesn't mention prerequisites, side effects, or appropriate contexts for invoking this unsubscribe operation versus other subscription management approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_update_preferencesC
Update communication preferences for a contact
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| subscriptionId | Yes | ||
| preferences | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation (implying mutation), but doesn't mention permissions required, whether changes are reversible, rate limits, or what happens to existing preferences not mentioned. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for what it communicates, though it could benefit from additional context given the complexity of the operation.
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 3 parameters (including a nested object), 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, what permissions are needed, how to structure the preferences object, or how this differs from similar sibling tools. The agent would struggle 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?
Schema description coverage is 0%, meaning all 3 parameters are undocumented in the schema. The description mentions 'communication preferences' which hints at the 'preferences' parameter, but doesn't explain what 'contactId' or 'subscriptionId' represent, nor does it clarify the structure of the preferences object. The description adds minimal value beyond what's implied by parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and target ('communication preferences for a contact'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'communications_update_subscription_status' or 'communications_subscribe_contact', leaving some ambiguity about when to choose this tool over those alternatives.
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 like 'communications_update_subscription_status' or 'communications_subscribe_contact'. There's no mention of prerequisites, context, or comparison with sibling tools, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
communications_update_subscription_statusC
Update subscription status for multiple contacts
| Name | Required | Description | Default |
|---|---|---|---|
| subscriptionId | Yes | ||
| updates | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's an update operation. It doesn't disclose critical behavioral traits: whether this is a mutation (implied but not explicit), permission requirements, rate limits, error handling, or what happens to contacts not in the updates array. For a batch mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the core action, making it easy to parse 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?
For a batch mutation tool with 2 parameters (including a complex nested array), 0% schema coverage, no annotations, and no output schema, the description is incomplete. It lacks information on behavior, parameters, outcomes, and error cases, leaving the agent under-informed about this potentially impactful operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'subscriptionId' refers to, the structure of 'updates' array, or the meaning of enum values like 'SUBSCRIBED' or 'LEGITIMATE_INTEREST_CLIENT'. This leaves parameters semantically undocumented.
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 'Update subscription status for multiple contacts' clearly states the verb ('Update'), resource ('subscription status'), and scope ('multiple contacts'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'communications_subscribe_contact' or 'communications_unsubscribe_contact' which handle individual contacts, so it doesn't reach the highest score.
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. It doesn't mention prerequisites (e.g., needing subscriptionId), compare to single-contact tools like 'communications_subscribe_contact', or specify use cases like batch updates. This leaves the agent without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_archive_associationC
Archive (delete) an association between two objects
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes | ||
| fromObjectId | Yes | ||
| toObjectId | Yes |
TDQS
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 indicates this is a destructive operation ('Archive (delete)'), but doesn't specify whether archiving is reversible, what permissions are required, whether there are side effects, or what the response looks like. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a tool with a straightforward purpose, though the brevity comes at the cost of missing important contextual information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with 4 parameters (0% schema coverage), no annotations, and no output schema, the description is inadequate. It doesn't explain parameter meanings, behavioral implications, or what happens after the operation. The agent lacks critical information 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 schema has 0% description coverage, and the tool description provides no information about the four required parameters. The agent must infer from parameter names alone what 'fromObjectType', 'toObjectType', 'fromObjectId', and 'toObjectId' mean and how they work together to identify the association to archive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and the target ('an association between two objects'), providing a specific verb+resource combination. However, it doesn't differentiate this tool from sibling tools like 'crm_archive_object' or 'crm_batch_archive_associations' beyond the singular vs. batch distinction implied by the names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'crm_batch_archive_associations' for multiple deletions or 'crm_archive_object' for archiving objects themselves. The description only states what the tool does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_archive_objectC
Archive (delete) a CRM object
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| objectId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'archive (delete)' which implies destructive action, but doesn't specify whether this is reversible, what permissions are required, whether it's a soft/hard delete, or what happens to associated data. For a destructive operation with zero annotation coverage, this is insufficient.
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 at just three words, front-loading the essential action. Every word earns its place with no redundancy or unnecessary elaboration.
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 destructive operation with 2 parameters, 0% schema description coverage, and no output schema, the description is inadequate. It doesn't explain what happens after archiving, what errors might occur, or provide any context about the CRM system's archiving behavior. The agent would struggle 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?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'a CRM object' but doesn't explain what objectType or objectId represent, what values are valid for objectType, or how objectId should be formatted. It fails to compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('archive/delete') and resource ('a CRM object'), making the purpose unambiguous. It doesn't explicitly differentiate from sibling tools like 'crm_batch_archive_objects' or 'crm_archive_association', but the singular vs. plural naming provides some implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like batch operations or other deletion methods. The description doesn't mention prerequisites, constraints, or typical use cases for archiving individual objects versus batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_archive_associationsC
Archive (delete) multiple associations in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes | ||
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool archives/deletes multiple associations, implying a destructive mutation, but doesn't address critical aspects like whether deletions are permanent/reversible, required permissions, rate limits, error handling for partial failures, or what the response contains. For a batch deletion tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action ('Archive (delete) multiple associations') and adds necessary context ('in a single request'). Every word earns its place, making it appropriately concise 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?
For a batch deletion tool with 3 parameters (including complex nested structures), 0% schema description coverage, no annotations, and no output schema, the description is insufficient. It covers the basic purpose but misses critical context: parameter meanings, behavioral details (permanence, permissions, error handling), and output expectations. The agent would struggle to use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'fromObjectType' and 'toObjectType' represent (the object types being associated), what valid values are (though enums are in schema), or the structure of 'inputs' array (containing from/to objects with IDs). The description provides zero guidance beyond the schema's raw structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete) multiple associations') and the scope ('in a single request'), which provides a specific verb+resource combination. It distinguishes from the singular 'crm_archive_association' sibling tool by emphasizing the batch/multiple aspect, though it doesn't explicitly contrast with other batch operations like 'crm_batch_create_associations'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when-not-to-use scenarios, or compare it to sibling tools like 'crm_archive_association' (for single deletions) or 'crm_batch_create_associations' (for batch creation). The agent must infer usage from the name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_archive_objectsC
Archive (delete) multiple CRM objects in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| objectIds | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states the tool archives (deletes) multiple objects, implying a destructive mutation, but lacks details on permissions required, whether deletions are reversible, rate limits, error handling for partial failures, or confirmation prompts. The parenthetical '(delete)' clarifies the destructive nature, but more behavioral context is needed for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It front-loads the core action and resource, 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?
For a destructive batch operation with no annotations, 0% schema description coverage, and no output schema, the description is insufficient. It doesn't cover critical aspects like side effects, return values, error conditions, or usage constraints, leaving significant gaps for an AI agent to use the tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'multiple CRM objects' hinting at objectIds as an array, but doesn't explain objectType enum values or constraints (e.g., ID formats, batch size limits). The description adds minimal value beyond the schema, resulting in a baseline score for inadequate parameter explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete) multiple CRM objects') and resource ('CRM objects') with the scope of 'in a single request.' It distinguishes from single-object operations but doesn't explicitly differentiate from other batch archive tools like 'crm_batch_archive_associations' or domain-specific batch archives (e.g., 'calls_batch_archive').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., permissions), compare to 'crm_archive_object' for single objects, or specify scenarios where batch archiving is appropriate versus individual deletions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_create_associationsC
Create multiple associations in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes | ||
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create' implies a write/mutation operation, but the description doesn't mention permissions required, whether associations are reversible, rate limits, error handling for partial failures, or what happens on success. For a batch creation tool with complex nested parameters, this is a significant gap in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 7 words, with zero wasted language. It's front-loaded with the core action ('Create multiple associations') and adds necessary scope ('in a single request'). Every word earns its place, making it efficient despite its informational shortcomings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters with nested objects, 0% schema description coverage, no annotations, no output schema), the description is inadequate. A batch creation tool for CRM associations needs more context about what associations are, how they work, success/failure behavior, and parameter meanings. The current description leaves too many gaps for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. The three parameters (fromObjectType, toObjectType, inputs) and their complex nested structure (including arrays of objects with specific required fields) are completely undocumented in the description. The agent must rely solely on the schema without any semantic explanation of what these parameters represent.
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 action ('create multiple associations') and scope ('in a single request'), which is clear but basic. It doesn't specify what 'associations' are in this CRM context or distinguish this from sibling tools like 'crm_create_association' (singular) or 'crm_batch_create_objects' (different resource type). The purpose is understandable but lacks specificity about the resource being manipulated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention when batch creation is preferable to single creation (crm_create_association), what prerequisites exist, or how it differs from other batch operations like crm_batch_create_objects. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_create_companiesC
Create multiple companies in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
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 states it's a creation tool but doesn't mention whether it's idempotent, how errors are handled (e.g., partial failures), rate limits, authentication requirements, or what the response contains (e.g., success/failure status, created IDs). This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core purpose and efficiently conveys the batch nature of the operation.
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 no annotations, no output schema, and complex nested parameters (17+ properties per company), the description is insufficient. It lacks critical context on error handling, response format, permissions, and parameter details, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'multiple companies' but provides no details about the 'inputs' parameter structure, required fields (like 'name'), optional properties, or the 'associations' field. The description adds minimal value beyond the schema's existence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple companies') and resource ('companies'), and specifies it's done 'in a single request', which distinguishes it from single-create operations. However, it doesn't explicitly differentiate from other batch creation tools like 'crm_batch_create_contacts' or 'crm_batch_create_leads' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., required permissions), compare it to single-company creation ('crm_create_company'), or explain trade-offs like error handling in batch operations versus individual requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_create_contactsC
Create multiple contacts in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It states the tool creates contacts, implying a write operation, but lacks details on permissions, rate limits, error handling, or response format. This leaves significant gaps in understanding how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words, making it highly concise and front-loaded. It efficiently communicates the core function without any structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (with nested objects and multiple properties), lack of annotations, and no output schema, the description is insufficient. It does not address parameter details, behavioral aspects, or usage context, making it incomplete for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning parameters are undocumented in the schema. The description mentions 'multiple contacts' but does not explain the 'inputs' parameter structure, required fields, or data formats. It adds minimal value beyond the schema, failing to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple contacts') and the resource ('contacts'), making the purpose evident. However, it does not differentiate this tool from its sibling 'crm_create_contact' or other batch tools like 'crm_batch_create_companies', leaving room for ambiguity in tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'crm_create_contact' for single contacts or other batch tools for different resources. There is no mention of prerequisites, constraints, or typical use cases, which limits its helpfulness in context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_create_leadsC
Create multiple leads in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a creation tool, implying mutation, but doesn't cover critical aspects like required permissions, rate limits, error handling, or whether it's idempotent. The description is too minimal to inform the agent adequately about behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded and efficiently conveys the core action, making it easy to parse 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 complexity of the input schema (deeply nested with many properties), lack of annotations, and no output schema, the description is severely incomplete. It fails to address parameter usage, behavioral expectations, or output format, leaving the agent with insufficient information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about parameters. With schema description coverage at 0% and a complex nested parameter structure (e.g., 'inputs' array with 'properties' and 'associations'), the agent lacks essential context on how to structure the input, what fields are mandatory, or the meaning of nested objects like 'associations'. This significantly hampers usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create multiple leads') and resource ('leads'), making the purpose specific and understandable. However, it doesn't differentiate from sibling tools like 'crm_batch_create_companies' or 'crm_batch_create_contacts', which have similar batch creation patterns but for different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention when to prefer batch creation over single creation ('crm_create_lead') or how it relates to other batch tools like 'crm_batch_update_leads'. The description lacks context about prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_create_objectsC
Create multiple CRM objects in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Create' implying mutation but doesn't disclose behavioral traits like permissions needed, rate limits, whether it's idempotent, error handling for partial failures, or response format. For a batch mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and 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 a batch mutation tool with 2 parameters (including complex nested objects), 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It lacks details on usage, behavior, parameters, and expected outcomes, leaving significant gaps 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?
Schema description coverage is 0%, so the description must compensate. It mentions 'multiple CRM objects' hinting at an array input but doesn't explain the 'objectType' enum or 'inputs' structure with 'properties' and 'associations'. The description adds minimal value beyond what's inferable from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple') and resource ('CRM objects'), specifying it's a batch operation ('in a single request'). It distinguishes from single-create tools like 'crm_create_object' but doesn't explicitly differentiate from other batch create tools like 'crm_batch_create_companies' or 'crm_batch_create_contacts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like single-object creation tools or type-specific batch tools (e.g., 'crm_batch_create_companies'). The description implies batch creation but doesn't specify scenarios, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_read_objectsD
Create multiple CRM objects in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| propertiesWithHistory | No | ||
| idProperty | No | ||
| objectIds | Yes | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. However, the description incorrectly claims a create operation, which contradicts the likely read behavior implied by the name and schema (which includes parameters like 'objectIds' for reading specific objects). This misrepresentation fails to provide any accurate behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is under-specified and misleading. While it avoids unnecessary length, it fails to provide meaningful information, making it ineffective rather than efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 5 parameters with 0% schema coverage, no annotations, no output schema, and a misleading description, the description is completely inadequate. It does not clarify the tool's purpose, usage, behavior, or parameters, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 5 parameters are documented in the schema. The description does not mention any parameters or their purposes, failing to compensate for the lack of schema documentation. Parameters like 'objectType', 'objectIds', and 'properties' remain unexplained.
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 'Create multiple CRM objects in a single request' is misleading and contradicts the tool's name 'crm_batch_read_objects' and input schema. The name suggests a read operation, while the description incorrectly states a create operation. This creates confusion about the tool's actual purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With numerous sibling tools like crm_batch_read, crm_get_object, crm_list_objects, and crm_search_objects, there is no indication of how this tool differs or when it should be preferred over other read operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_update_companiesC
Update multiple companies in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
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. 'Update multiple companies' implies a write/mutation operation, but it doesn't describe permissions required, whether updates are partial or full, error handling for invalid inputs, rate limits, or response format. This is a significant gap for a batch mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's appropriately sized and front-loaded, immediately conveying the core functionality without unnecessary elaboration.
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 mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It lacks critical context about permissions, error handling, input structure, and expected responses, leaving the agent poorly equipped 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?
Schema description coverage is 0%, so the description must compensate but fails to do so. It mentions 'multiple companies' but doesn't explain the 'inputs' parameter structure, required 'id' and 'properties' fields, or the nested properties like 'lifecyclestage' with its enum values. The description adds no meaningful parameter details beyond what's inferred from the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update multiple companies') and resource ('companies'), making the purpose immediately understandable. It distinguishes from single-update tools like 'crm_update_company' by specifying 'in a single request' for batch operations, though it doesn't explicitly differentiate from other batch tools like 'crm_batch_update_contacts' or 'crm_batch_update_objects'.
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. It doesn't mention prerequisites (e.g., needing company IDs), compare it to single-update tools like 'crm_update_company' or other batch tools like 'crm_batch_update_objects', or specify use cases like bulk data correction or mass updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_update_contactsC
Update multiple contacts in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but provides minimal behavioral information. It states it's an update operation (implying mutation) but doesn't disclose permission requirements, rate limits, whether updates are atomic/partial, error handling for failed items in batch, or what the response contains. The description doesn't contradict annotations (none exist), but fails to provide essential context for a batch mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 6 words with zero wasted language. It's front-loaded with the core action and resource. Every word earns its place by specifying 'update' (action), 'multiple contacts' (resource and scope), and 'in a single request' (batch characteristic).
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 mutation tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain the complex nested parameter structure, doesn't provide usage context versus siblings, and lacks behavioral details about permissions, error handling, or response format. The schema handles parameter documentation, but the description fails to add necessary context for effective tool selection and use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but doesn't. It mentions 'multiple contacts' which hints at the array structure, but provides no details about the 'inputs' parameter, required fields, property formats, or enum values for lifecyclestage/leadstatus. The schema comprehensively documents the structure, but the description adds almost no semantic value beyond implying batch processing.
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 'Update multiple contacts in a single request' clearly states the action (update) and resource (contacts), but it's vague about scope and doesn't differentiate from siblings like crm_update_contact (single update) or crm_batch_update_companies/leads/objects (other batch updates). It specifies 'multiple' and 'in a single request' which adds some context, but lacks specificity about what constitutes 'multiple' or how it differs from other 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?
No explicit guidance on when to use this tool versus alternatives. The description doesn't mention when to choose batch update over single updates (crm_update_contact) or other batch operations (crm_batch_update_companies, crm_batch_update_leads). It also doesn't provide prerequisites, limitations, or error handling considerations for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_update_leadsC
Update multiple leads in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is an update operation but doesn't disclose behavioral traits like whether it requires specific permissions, if updates are atomic or partial, error handling for invalid inputs, rate limits, or what the response contains. This is inadequate for a mutation tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the core functionality without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a batch update operation, no annotations, and no output schema, the description is insufficient. It lacks critical context about behavior, error handling, permissions, and response format, making it incomplete for safe and effective use by 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?
Schema description coverage is 0%, but the description adds minimal value beyond the schema. It implies an array of lead updates but doesn't explain the structure or semantics of 'inputs' beyond what the schema already defines. With 1 parameter documented in the schema, the baseline is 3 as the schema does the heavy lifting, but the description doesn't compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('multiple leads'), making the purpose evident. However, it doesn't distinguish this tool from sibling batch tools like 'crm_batch_update_companies' or 'crm_batch_update_contacts', which follow the same pattern for different CRM objects.
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 like 'crm_update_lead' (for single updates) or other batch tools. It mentions 'in a single request' but doesn't explain the trade-offs or prerequisites for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_batch_update_objectsC
Update multiple CRM objects in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's an update operation. It doesn't disclose critical behavioral traits like required permissions, whether updates are partial/full, error handling for partial failures, rate limits, or what happens to unspecified properties. 'Update multiple' implies mutation but lacks detail on consequences.
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?
Extremely concise single sentence with zero wasted words. Front-loaded with the core action ('Update multiple CRM objects') followed by operational context ('in a single request'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is inadequate. It doesn't explain what gets updated, how properties are handled, error responses, or return values. Given the complexity of batch operations and lack of structured documentation, more context is needed for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'objectType' enum values represent or the structure of 'inputs' array with id/properties objects. However, the schema itself is relatively clear with enum and nested structure, providing a baseline understanding despite the description gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update multiple') and resource ('CRM objects') with the operational context ('in a single request'). It distinguishes from single-update tools like crm_update_object but doesn't explicitly differentiate from other batch tools like crm_batch_update_companies or crm_batch_update_contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like crm_batch_update_companies, crm_batch_update_contacts, or crm_batch_update_leads. The description implies batch operations but doesn't specify use cases, prerequisites, or exclusions compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_associationC
Create an association between two objects
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes | ||
| fromObjectId | Yes | ||
| toObjectId | Yes | ||
| associationTypes | Yes |
TDQS
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 states 'Create,' implying a write/mutation operation, but doesn't address permissions, side effects, error handling, or response format. This leaves significant gaps in understanding the tool's behavior and risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for its minimal content, though this conciseness comes at the cost of detail and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a 5-parameter mutation tool with no annotations and 0% schema coverage, the description is inadequate. It lacks details on behavior, parameters, output, and context, failing to provide enough information for safe and effective use by 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?
Schema description coverage is 0%, so the description must compensate but adds no parameter details. It doesn't explain the meaning of 'fromObjectType,' 'toObjectType,' 'associationTypes,' or their relationships, leaving all 5 parameters undocumented and unclear beyond the schema's basic structure.
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 action ('Create an association') and resource ('between two objects'), which is clear but vague. It doesn't specify what types of objects can be associated or distinguish this from sibling tools like crm_batch_create_associations or crm_get_associations, leaving room for ambiguity about scope and 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?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, such as needing existing objects to associate, and doesn't mention sibling tools like crm_batch_create_associations for bulk operations or crm_get_associations for retrieval, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_companyC
Create a new company with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create' implies a write/mutation operation, but it doesn't disclose important behavioral traits like required permissions, whether the operation is idempotent, what validation entails, error handling, or what happens on success. The mention of 'validated properties' hints at input validation but doesn't explain what validation occurs or its consequences.
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 at just 6 words, front-loading the core purpose with zero wasted words. Every word earns its place by conveying essential information about 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?
For a creation tool with complex nested parameters (2 parameters with deep nesting), no annotations, and no output schema, the description is insufficient. It doesn't explain what happens after creation (return values, IDs), doesn't cover parameter details, and provides minimal behavioral context. The conciseness comes at the expense of completeness for this moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It mentions 'validated properties' which relates to the 'properties' parameter, but doesn't explain what properties are available, their formats, or required fields. It completely ignores the 'associations' parameter. For a tool with 2 parameters (one complex nested object), this minimal parameter guidance is inadequate.
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 'Create a new company with validated properties' clearly states the verb ('Create') and resource ('company'), and the 'validated properties' adds specificity about input handling. However, it doesn't explicitly differentiate from sibling tools like crm_create_contact or crm_create_lead, which are similar creation operations for different CRM entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are many sibling tools for creating different CRM entities (companies, contacts, leads, objects) and batch operations, but the description doesn't mention any of these alternatives or specify prerequisites for company creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_company_propertyC
Create a new company property
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| label | Yes | ||
| type | Yes | ||
| fieldType | Yes | ||
| groupName | Yes | ||
| description | No | ||
| options | No | ||
| displayOrder | No | ||
| hasUniqueValue | No | ||
| hidden | No | ||
| formField | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write/mutation operation, the description doesn't address permissions required, whether the operation is idempotent, what happens on conflicts, rate limits, or what the response contains. For a creation tool with 11 parameters and no annotation coverage, this is a significant gap in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single sentence with no wasted words. It's front-loaded with the core purpose. While this brevity comes at the cost of completeness, as a standalone statement it's efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 11 parameters, 0% schema description coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain what a 'company property' is in this context, doesn't describe parameter meanings, doesn't provide behavioral context, and offers no guidance on usage. The description fails to compensate for the lack of structured documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 11 parameters have descriptions in the schema. The tool description provides no information about any parameters, their purposes, relationships, or constraints. This leaves the agent with only raw schema structure without semantic understanding of what each field means.
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 'Create a new company property' clearly states the action (create) and resource (company property), which is adequate. However, it doesn't differentiate from sibling tools like crm_create_contact_property or crm_create_lead_property, leaving ambiguity about when to use this specific tool versus other property creation 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?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, dependencies, or comparison to sibling tools like crm_create_contact_property or crm_create_lead_property. It simply states what the tool does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_contactC
Create a new contact with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions 'validated properties' without explaining validation rules, error handling, permissions required, or mutation effects. It lacks details on rate limits, idempotency, or response format, leaving behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse 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?
For a creation tool with 2 parameters (including nested objects), 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't compensate for missing context on inputs, behavior, or outputs, leaving the agent under-informed.
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 0%, and the description doesn't explain the two parameters (properties and associations) beyond implying validation. It fails to clarify what 'properties' includes or how 'associations' work, adding minimal value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('contact'), distinguishing it from sibling tools like crm_create_company or crm_create_lead. However, it doesn't explicitly differentiate from crm_create_object or crm_batch_create_contacts, which reduces specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like crm_batch_create_contacts or crm_create_object. The mention of 'validated properties' hints at data quality but doesn't specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_contact_propertyC
Create a new contact property
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| label | Yes | ||
| type | Yes | ||
| fieldType | Yes | ||
| groupName | Yes | ||
| description | No | ||
| options | No | ||
| displayOrder | No | ||
| hasUniqueValue | No | ||
| hidden | No | ||
| formField | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Create' implies a write/mutation operation, but the description doesn't mention permissions required, whether this affects existing contacts, rate limits, or what happens on success/failure. For a creation tool with 11 parameters and no annotation coverage, this is a significant gap in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is maximally concise - a single sentence with no wasted words. It's front-loaded with the essential action and resource. While it's under-specified, what's there is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex creation tool with 11 parameters (5 required), 0% schema description coverage, no annotations, and no output schema, the description is completely inadequate. It doesn't explain what a 'contact property' is, how it's used, what the parameters mean, or what the tool returns. The agent would struggle 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 schema has 0% description coverage, meaning none of the 11 parameters have schema-level documentation. The description provides zero information about any parameters - not even mentioning the 5 required ones (name, label, type, fieldType, groupName). For a complex tool with 11 parameters and no schema descriptions, the description fails to compensate at all.
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 'Create a new contact property' clearly states the action (create) and resource (contact property), which is better than a tautology. However, it doesn't distinguish this tool from its sibling 'crm_create_company_property' or 'crm_create_lead_property' - all follow the same 'create X property' pattern without differentiation. The purpose is clear but lacks sibling distinction.
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. There's no mention of prerequisites, when to use batch operations instead, or how this relates to other property management tools like 'crm_get_contact_properties'. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_leadC
Create a new lead with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
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 mentions 'validated properties' but doesn't explain what validation entails (e.g., format checks, required fields, error handling). It also omits critical details like whether this is a mutating operation, what happens on success/failure, or if there are 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 extremely concise with a single sentence that front-loads the core action. There is no wasted verbiage, making it efficient in structure, though this brevity contributes to gaps in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters with nested objects, 0% schema coverage, no annotations, no output schema), the description is insufficient. It doesn't explain the return value, error conditions, or the semantics of key parameters like 'associations', leaving the agent with inadequate information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal value beyond the input schema, which has 0% schema description coverage. It hints at 'validated properties' but doesn't clarify which properties are mandatory, their validation rules, or the purpose of the 'associations' parameter. With two parameters (one required) and complex nested structures, the description fails to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new lead'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'crm_create_contact' or 'crm_create_company', which have similar creation patterns but target different CRM objects.
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 like 'crm_batch_create_leads' for bulk operations or 'crm_update_lead' for modifications. It also lacks prerequisites, such as required permissions or system states needed for lead creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_lead_propertyD
Create a new lead property
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| label | Yes | ||
| type | Yes | ||
| fieldType | Yes | ||
| groupName | Yes | ||
| description | No | ||
| options | No | ||
| displayOrder | No | ||
| hasUniqueValue | No | ||
| hidden | No | ||
| formField | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'create' implying a write operation but fails to mention permissions required, side effects, whether the creation is reversible, rate limits, or what happens on success/failure. For a mutation tool with 11 parameters, this lack of behavioral context is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is front-loaded and appropriately sized for its content, though the brevity contributes to its inadequacy in other dimensions. The structure is clear but under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, 5 required), 0% schema description coverage, no annotations, and no output schema, the description is severely incomplete. It does not compensate for the lack of structured data, failing to provide necessary context for a mutation tool with multiple parameters and enums.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 11 parameters have descriptions in the schema. The tool description adds no parameter information beyond the name, failing to explain what 'name', 'label', 'type', 'fieldType', 'groupName', or other parameters mean. This leaves all parameters undocumented.
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 'Create a new lead property' restates the tool name (crm_create_lead_property) with minimal elaboration. It specifies the verb 'create' and resource 'lead property' but lacks detail on what a lead property is or how it differs from similar tools like crm_create_company_property or crm_create_contact_property. This is a tautology with no sibling 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 no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, when this tool is appropriate, or what distinguishes it from other property creation tools (e.g., crm_create_company_property). This absence of context leaves the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_create_objectD
Create a new CRM object
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| properties | Yes | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action ('Create') without mentioning permissions, side effects, error handling, or response format. This leaves critical aspects like mutation impact, authentication needs, or rate limits unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is front-loaded and efficiently conveys the basic action, though this brevity comes at the cost of detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, nested objects, no output schema, and no annotations), the description is severely inadequate. It does not explain parameter usage, behavioral expectations, or how it fits among sibling tools, leaving the agent with insufficient information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning parameters are undocumented in the schema. The description adds no information about the three parameters (objectType, properties, associations), their purposes, or expected formats. It fails to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new CRM object' restates the tool name with minimal elaboration, making it tautological. While it specifies the resource (CRM object), it lacks detail about what constitutes a CRM object or how it differs from sibling tools like crm_create_company or crm_create_contact, which are more specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools (e.g., crm_create_company, crm_create_contact, crm_batch_create_objects), the description fails to indicate scenarios where this generic creation tool is preferred over specific ones or batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_associationsC
Get all associations of a specific type between objects
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes | ||
| fromObjectId | Yes | ||
| after | No | ||
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Get all associations,' implying a read-only operation, but doesn't disclose behavioral traits like pagination (hinted by 'after' and 'limit' parameters), rate limits, authentication needs, or what 'all' means in context (e.g., if it returns a complete list or requires pagination). The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it directly states the tool's function without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse 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 complexity (5 parameters, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits (e.g., pagination, errors), parameter meanings, and output format. For a tool that retrieves associations between objects, more context is needed to guide effective use, especially with 0% schema coverage and no annotations.
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 0%, so the description must compensate for undocumented parameters. It mentions 'associations of a specific type between objects,' which loosely relates to 'fromObjectType' and 'toObjectType,' but doesn't explain the meaning of parameters like 'fromObjectId,' 'after' (for pagination), or 'limit' (for result size). With 5 parameters and no schema descriptions, the description adds very little semantic 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 verb ('Get') and resource ('associations of a specific type between objects'), making the purpose understandable. It distinguishes from sibling tools like 'crm_list_association_types' (which lists types rather than instances) and 'crm_get_object' (which retrieves single objects rather than associations). However, it doesn't explicitly mention the CRM context or differentiate from other 'get' tools like 'crm_get_company'.
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. It doesn't mention prerequisites (e.g., needing valid object IDs), exclusions (e.g., not for creating associations), or comparisons to sibling tools like 'crm_list_objects' or 'crm_search_objects' that might retrieve related data. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_companyC
Get a single company by ID with specific properties and associations
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, it doesn't clarify authentication requirements, rate limits, error conditions, or what happens when invalid IDs or parameters are provided. The description mentions 'specific properties and associations' but doesn't explain the behavior around partial data retrieval or default responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately front-loaded with the main purpose. While it could potentially be more structured with separate clauses for different aspects, it achieves good conciseness for its 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?
For a tool with 3 parameters, 0% schema description coverage, no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, error handling, authentication needs, or provide examples. While it states the basic purpose, it leaves too many contextual gaps for a tool that retrieves specific data with filtering parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the schema provides no parameter documentation. The description mentions 'by ID with specific properties and associations' which hints at the three parameters (companyId, properties, associations), but doesn't explain their formats, constraints, or optionality. It adds some semantic meaning but doesn't fully compensate for the complete lack of schema 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 clearly states the verb 'Get' and resource 'a single company by ID', making the purpose understandable. It adds specificity about 'with specific properties and associations' which distinguishes it from a basic get operation. However, it doesn't explicitly differentiate from sibling tools like crm_get_object or crm_search_companies, which prevents a perfect score.
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 many sibling tools available (like crm_get_object, crm_search_companies, crm_batch_read_objects), there's no indication of when this specific company retrieval tool is preferred or what prerequisites might exist. The description only states what it does, not 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.
crm_get_company_propertiesC
Get all properties for companies
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'Get' operation, implying read-only behavior, but doesn't clarify important aspects like whether it requires authentication, returns paginated results, has rate limits, or what format the properties are returned in. The description is too minimal to provide adequate behavioral context for a tool with parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words, with zero wasted language. It's front-loaded with the core action and resource. While this conciseness comes at the cost of completeness, the structure itself is efficient with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters (0% schema coverage), no annotations, and no output schema, the description is inadequate. It doesn't explain what 'properties' means in this context (metadata vs. values), doesn't address the parameters, and provides no information about the return format or behavior. The minimal description leaves too many gaps for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its 2 parameters ('archived' and 'properties'), and the tool description provides no information about what these parameters mean or how they affect the operation. The description doesn't mention any parameters at all, leaving the agent to guess about their purpose and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all properties for companies' clearly states the verb ('Get') and resource ('properties for companies'), making the basic purpose understandable. However, it doesn't specify whether this retrieves metadata about company properties or actual property values, nor does it differentiate from sibling tools like 'crm_get_company' or 'crm_get_contact_properties' that might have overlapping 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 no guidance on when to use this tool versus alternatives. There are multiple sibling tools related to CRM properties (e.g., 'crm_get_contact_properties', 'crm_get_lead_properties') and company operations (e.g., 'crm_get_company', 'crm_search_companies'), but the description doesn't indicate when this specific tool is appropriate or what distinguishes it from those options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_contactC
Get a single contact by ID with specific properties and associations
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is a 'Get' operation, implying read-only behavior, but doesn't disclose authentication requirements, rate limits, error conditions, or what happens with invalid IDs. For a read operation with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently conveys the core purpose. No wasted words, though it could be slightly more structured by separating parameter guidance. The front-loaded information is clear and direct.
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 tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or provide enough parameter detail. Given the complexity and lack of structured support, it should do more to guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'specific properties and associations' which maps to the 'properties' and 'associations' parameters, and 'by ID' maps to 'contactId'. However, it doesn't explain the format of property names, the meaning of association types, or provide examples. It adds basic meaning but leaves parameters under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'contact by ID', specifying it retrieves 'a single contact' with 'specific properties and associations'. It distinguishes from list/search siblings by focusing on single-record retrieval, though it doesn't explicitly name alternatives like crm_search_contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for retrieving a specific contact when the ID is known, but doesn't mention when to choose crm_get_contact over crm_search_contacts or crm_batch_read_objects, nor does it discuss prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_contact_propertiesC
Get all properties for contacts
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get all properties for contacts' implies a read-only operation, but it doesn't specify whether this requires authentication, has rate limits, returns paginated results, or handles errors. For a tool with zero annotation coverage, this leaves critical behavioral traits unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action ('Get all properties for contacts'), making it easy to parse quickly. Every word contributes directly to the tool's 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 (2 parameters with 0% schema coverage, no annotations, and no output schema), the description is incomplete. It doesn't explain parameter usage, return values, or behavioral constraints, leaving the agent with insufficient information to invoke the tool correctly in a real-world context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'all properties' but doesn't explain the two parameters ('archived' and 'properties') from the input schema, which has 0% schema description coverage. It fails to clarify what 'archived' filters or what 'properties' array contains (e.g., specific property names). With low schema coverage, the description doesn't compensate adequately for undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all properties for contacts' clearly states the verb ('Get') and resource ('properties for contacts'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'crm_get_contact' (which gets contact details) or 'crm_get_company_properties' (which gets properties for companies), leaving ambiguity about when to use this specific tool versus related ones.
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 'crm_get_contact' (for contact details) and 'crm_get_company_properties' (for company properties), there's no indication of context, prerequisites, or exclusions. This forces the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_leadC
Get a single lead by ID with specific properties and associations
| Name | Required | Description | Default |
|---|---|---|---|
| leadId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what the tool does, not how it behaves. It doesn't disclose whether this is a read-only operation, what permissions are required, error handling for invalid IDs, rate limits, or response format. 'Get' implies safe retrieval, but no explicit safety guarantees are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that efficiently conveys core functionality without wasted words. It's front-loaded with the main purpose, though could be slightly more structured by separating ID requirement from optional fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations, 0% schema coverage, and no output schema, the description is insufficient. It doesn't explain return values, error cases, or behavioral nuances. While it covers the basic action, it lacks depth needed for safe and effective use by 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?
Schema description coverage is 0%, but the description mentions 'by ID with specific properties and associations', which maps to the three parameters (leadId, properties, associations). However, it doesn't explain parameter formats, optionality, or the meaning of 'specific properties' versus the schema's generic array. The description adds basic meaning but leaves significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('a single lead by ID') with additional scope ('with specific properties and associations'). It distinguishes from generic 'crm_get_object' by specifying lead retrieval, but doesn't explicitly differentiate from 'crm_get_lead_properties' which might overlap in 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?
No guidance on when to use this tool versus alternatives like 'crm_get_object' (for generic objects) or 'crm_get_lead_properties' (for properties only). The description implies it's for retrieving a specific lead with optional details, but doesn't mention prerequisites, error conditions, or comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_lead_propertiesC
Get all properties for leads
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but provides none. It doesn't indicate whether this is a read-only operation (though 'get' implies it), what permissions might be required, whether it returns paginated results, what format the properties come in, or any error conditions. For a tool with 2 parameters and no annotation coverage, this is a significant transparency gap.
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 at just 5 words. It's front-loaded with the core action and resource. There's no wasted language or unnecessary elaboration. While it may be too brief for completeness, as a standalone statement it's efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters with 0% schema coverage, no annotations, no output schema, and multiple sibling tools in the CRM domain, the description is completely inadequate. It doesn't explain parameter usage, behavioral characteristics, return format, or differentiation from similar tools. For a property retrieval operation in a complex CRM system, this leaves the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so parameters 'archived' and 'properties' are completely undocumented in the schema. The description adds no information about these parameters - it doesn't explain what 'archived' filters, what the 'properties' array should contain, or whether both are optional. With 2 undocumented parameters and no compensation in the description, this is inadequate.
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 'Get all properties for leads' clearly states the action (get) and resource (lead properties), but it's somewhat vague about scope and doesn't differentiate from sibling tools like crm_get_lead (which presumably gets lead data rather than properties) or crm_get_company_properties/crm_get_contact_properties (which get properties for other entity types). The purpose is understandable but lacks specificity about what 'properties' means in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With siblings like crm_get_lead (gets lead data), crm_search_leads (searches leads), and crm_create_lead_property (creates properties), there's no indication of when this specific property-retrieval tool is appropriate versus those other lead-related operations. Usage context is completely absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_get_objectC
Get a single CRM object by ID
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| objectId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden of behavioral disclosure. It states this is a 'Get' operation which implies read-only, but doesn't mention authentication requirements, rate limits, error conditions, or what happens with invalid IDs. For a tool with 4 parameters and no annotation coverage, this leaves significant behavioral gaps.
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 maximally concise - a single sentence that states the core purpose without any wasted words. It's front-loaded with the essential information and contains no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, how to interpret parameters, or provide any context about the CRM system. Given the complexity implied by the parameter structure and sibling tools, this description leaves too many unanswered questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 4 parameters, the description provides no information about any parameters. It doesn't explain what 'objectType' accepts, what format 'objectId' expects, what 'properties' array should contain, or what 'associations' means. The description fails to compensate for the complete lack of schema 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 clearly states the action ('Get') and resource ('single CRM object by ID'), making the purpose immediately understandable. It distinguishes from list/search operations by specifying 'single' and 'by ID', though it doesn't explicitly differentiate from sibling tools like crm_get_company or crm_get_contact which appear to be more specific versions of this generic tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. With numerous sibling tools including specific object getters (crm_get_company, crm_get_contact, etc.) and batch operations, the description offers no indication of when this generic getter is preferred over the specific ones or when batch operations might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_list_association_typesC
List all available association types for a given object type pair
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | ||
| toObjectType | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a 'List' operation, implying read-only behavior, but doesn't clarify if it requires authentication, has rate limits, returns paginated results, or what format the output takes. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place with no redundancy or unnecessary elaboration. It's appropriately sized for a straightforward list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what association types are, how they're used, what the output format looks like, or any error conditions. Given the complexity of CRM associations and lack of structured documentation, this leaves the agent with significant gaps in understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'for a given object type pair' which aligns with the two parameters (fromObjectType and toObjectType). However, with 0% schema description coverage, the schema provides enums but no descriptions. The description doesn't explain what these object types represent, what 'custom' means, or how the pair defines the association direction. It adds minimal value beyond what's implied by the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all available association types') with a specific scope ('for a given object type pair'). It distinguishes itself from other CRM tools by focusing on association types rather than objects or associations themselves. However, it doesn't explicitly differentiate from sibling tools like 'crm_get_associations' which might retrieve actual associations rather than types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for needing association types, or how this differs from other CRM tools like 'crm_get_associations' or 'crm_list_objects'. The agent must infer usage from the name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_list_objectsB
List CRM objects of a specific type with optional filtering and pagination
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| properties | No | ||
| after | No | ||
| limit | No | ||
| archived | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'optional filtering and pagination' which hints at some capabilities, but doesn't describe what 'list' entails operationally (e.g., is it read-only? Does it require specific permissions? What's the default sort order? Are there rate limits?). For a tool with 5 parameters and no annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates the core functionality. Every word earns its place: 'List' (action), 'CRM objects' (resource), 'specific type' (key constraint), 'optional filtering and pagination' (capabilities). No wasted words 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 complexity (5 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain return values (no output schema), doesn't clarify behavioral aspects like safety or permissions, and leaves most parameter semantics unclear. For a list operation with multiple filter options, this provides inadequate context for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'specific type' (mapping to objectType), 'optional filtering' (vaguely suggesting properties, archived, or other filters), and 'pagination' (hinting at after and limit). However, it doesn't explain what 'properties' array means, what 'after' cursor represents, or the meaning of the 'archived' flag. With 5 parameters and no schema descriptions, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('CRM objects of a specific type'), making the purpose immediately understandable. It distinguishes from siblings like crm_get_object (singular fetch) and crm_search_objects (search with queries), though it doesn't explicitly name these alternatives. The mention of 'specific type' aligns with the objectType parameter, providing good context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing objects with filtering and pagination, suggesting it's for bulk retrieval rather than single-object operations. However, it doesn't explicitly state when to use this versus alternatives like crm_search_objects (which might support more complex queries) or crm_batch_read_objects (which might handle multiple IDs). No explicit exclusions or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_search_companiesC
Search companies with company-specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'company-specific filters' but provides no information about permissions required, rate limits, pagination behavior (despite having 'limit' and 'after' parameters), what happens when no results match, or the format of returned data. This is inadequate for a search tool with complex filtering capabilities.
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 - a single 6-word sentence that gets straight to the point. There's no wasted language or unnecessary elaboration, making it easy to parse 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?
For a search tool with 5 parameters, complex nested filtering structures, no output schema, and no annotations, the description is completely inadequate. It doesn't explain what the tool returns, how to interpret results, error conditions, or how to properly use the sophisticated filtering capabilities indicated by the schema. The minimal description fails to provide necessary context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 5 parameters (filterGroups, properties, limit, after, sorts), the description provides no meaningful information about any parameters. 'company-specific filters' vaguely hints at filterGroups but doesn't explain the complex nested structure, available operators, or how to construct valid queries. The description fails to compensate for the complete lack of schema 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 'Search companies with company-specific filters' clearly states the verb ('Search') and resource ('companies'), but it's somewhat vague about what 'company-specific filters' means. It distinguishes from general search tools but doesn't specify how it differs from other CRM search tools like crm_search_contacts or crm_search_leads beyond the target resource.
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. There are multiple sibling search tools (crm_search_contacts, crm_search_leads, crm_search_objects), but no indication of when this company-specific search is preferred over those other options or general listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_search_contactsC
Search contacts with contact-specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'contact-specific filters' but doesn't disclose behavioral traits like pagination (implied by 'limit' and 'after' in schema), rate limits, authentication needs, or what the output looks like. For a search tool with 5 parameters and no output schema, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded and appropriately sized for a basic tool definition, though it could benefit from more detail given the 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 complexity (5 parameters, nested objects in schema, no output schema, and no annotations), the description is incomplete. It doesn't explain the input structure, output format, or usage context sufficiently. For a search tool with rich filtering capabilities, more guidance is needed to help an agent use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only vaguely references 'contact-specific filters', which partially relates to 'filterGroups', but doesn't explain the other 4 parameters (properties, limit, after, sorts) or their semantics. This adds minimal value beyond the schema, failing to address the coverage gap 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 'Search contacts with contact-specific filters' states the verb (search) and resource (contacts), but is vague about scope and differentiation. It doesn't specify what constitutes 'contact-specific filters' versus general filters, nor does it clearly distinguish from sibling tools like crm_search_companies or crm_search_leads beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage for searching contacts, but doesn't mention prerequisites, when to choose this over crm_list_objects or crm_get_contact, or any constraints. Sibling tools include other search variants, but no comparison is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_search_leadsC
Search leads with lead-specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but offers minimal information. It doesn't indicate whether this is a read-only operation, what permissions are required, how results are returned (e.g., pagination with 'after' parameter), rate limits, or error conditions. The mention of 'lead-specific filters' hints at filtering capability but lacks detail.
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 at just 5 words, with no wasted language. It's front-loaded with the core action ('Search leads'), though this brevity comes at the cost of completeness. Every word earns its place in conveying the basic intent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters with nested objects, 0% schema coverage, no output schema, no annotations), the description is inadequate. It doesn't explain how to construct filters, what properties are available for leads, how sorting works, or what the tool returns. For a search tool with rich filtering capabilities, this leaves too much undefined.
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 0%, so the description must compensate but fails to do so. It mentions 'lead-specific filters' which loosely relates to the 'filterGroups' parameter, but doesn't explain any of the 5 parameters (filterGroups, properties, limit, after, sorts) or their purposes. The description adds minimal value beyond the schema's structure.
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 'Search leads with lead-specific filters' states the verb ('Search') and resource ('leads'), making the basic purpose clear. However, it's vague about what 'lead-specific filters' means and doesn't distinguish this tool from sibling search tools like crm_search_companies or crm_search_contacts, which follow the same pattern for different CRM objects.
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. It doesn't mention sibling tools like crm_get_lead (for single lead retrieval) or crm_batch_read_objects (for batch operations), nor does it specify prerequisites or appropriate contexts for searching leads versus other CRM entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_search_objectsC
Search CRM objects using filters
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Search' implies a read operation, but the description doesn't mention whether this requires authentication, has rate limits, returns paginated results, or what happens with invalid filters. For a search tool with 6 parameters and complex filtering logic, this is inadequate.
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 at just 5 words, with zero wasted language. It's front-loaded with the core action and resource. While under-specified, it's not verbose or poorly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters with nested filtering logic, 0% schema coverage, no annotations, no output schema), the description is severely incomplete. It doesn't explain the search scope, result format, error handling, or how to interpret the various parameter types. For a sophisticated search tool, this minimal description is inadequate.
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 0%, so the description must compensate for undocumented parameters. The description only mentions 'filters' generally, ignoring the other 5 parameters (objectType, properties, limit, after, sorts). It doesn't explain what 'CRM objects' encompasses or how filters work, leaving critical parameter semantics unclear.
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 'Search CRM objects using filters' clearly states the verb ('search') and resource ('CRM objects'), but it's vague about what 'objects' means and doesn't distinguish this tool from sibling search tools like crm_search_companies, crm_search_contacts, and crm_search_leads. It provides a basic purpose but lacks specificity.
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 multiple sibling search tools for specific object types (companies, contacts, leads) and a general crm_list_objects, there's no indication of when this filtered search is preferred over those options. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_update_companyC
Update an existing company with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update' implies a mutation, but it doesn't specify permissions needed, whether changes are reversible, validation details beyond 'validated properties', or response format. The phrase 'validated properties' hints at input validation but lacks specifics on what validation entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point without unnecessary words. It's appropriately sized for a basic tool description, though it could benefit from being more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, 0% schema description coverage, no output schema, and 2 parameters (one being a complex nested object), the description is inadequate. It doesn't explain what happens after the update, error conditions, or provide enough context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter documentation. The description mentions 'validated properties' which loosely relates to the 'properties' parameter, but doesn't explain what 'companyId' is, what properties can be updated, or provide any examples. It adds minimal value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('an existing company'), making the purpose understandable. However, it doesn't differentiate this tool from sibling tools like crm_update_contact, crm_update_lead, or crm_update_object, which all follow the same pattern for different entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites like needing an existing company ID, nor does it contrast with batch update tools (crm_batch_update_companies) or other CRM update operations in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_update_contactC
Update an existing contact with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | ||
| properties | Yes |
TDQS
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 states this is an update operation but doesn't mention permissions required, whether changes are reversible, rate limits, or what happens to unspecified properties. 'Validated properties' hints at validation but doesn't explain the validation process or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a basic tool description and front-loads the 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?
For a mutation tool with no annotations, 0% schema description coverage, no output schema, and complex nested parameters, the description is inadequate. It doesn't address behavioral aspects like permissions or side effects, doesn't explain parameter usage, and provides minimal context for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds minimal semantic context by mentioning 'validated properties' which relates to the 'properties' parameter. However, it doesn't explain what 'contactId' represents or provide details about the nested properties object beyond validation. With 2 parameters and no schema descriptions, this provides some but insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('an existing contact'), making the purpose evident. However, it doesn't distinguish this tool from sibling tools like 'crm_update_company' or 'crm_update_lead', which have similar update patterns for different CRM entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'crm_batch_update_contacts' or 'crm_update_object'. It mentions 'validated properties' but doesn't explain what validation entails or when this tool is appropriate compared to other update methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_update_leadC
Update an existing lead with validated properties
| Name | Required | Description | Default |
|---|---|---|---|
| leadId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update' implies a mutation operation, but the description doesn't specify required permissions, whether updates are reversible, validation behavior beyond 'validated properties', or error handling. The mention of 'validated properties' hints at some validation but lacks detail on what validation entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. There's no wasted verbiage, and it's appropriately sized for a tool with a clear primary function. However, it could be more front-loaded with critical context about the tool's scope.
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 no annotations, no output schema, and 0% schema description coverage, the description is inadequate. It doesn't explain what happens after the update (success response, error cases), doesn't clarify the validation process, and provides minimal guidance on the complex nested 'properties' object with many possible fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'validated properties' which hints at the 'properties' parameter, but doesn't explain what 'leadId' is, what specific properties can be updated, or what 'validated' means. It adds minimal value beyond what's implied by the parameter names 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 action ('Update') and target resource ('an existing lead'), making the purpose immediately understandable. It distinguishes from sibling tools like 'crm_create_lead' by specifying 'existing', but doesn't differentiate from other update tools like 'crm_batch_update_leads' or 'crm_update_contact' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a lead ID), when to choose batch updates instead, or any constraints on usage. The agent must infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
crm_update_objectC
Update an existing CRM object
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| objectId | Yes | ||
| properties | Yes |
TDQS
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 states this is an update operation, implying mutation, but doesn't cover critical aspects like required permissions, whether changes are reversible, rate limits, or what happens to unspecified properties. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly, though this brevity contributes to gaps in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a mutation tool with 3 parameters, nested objects, no output schema, and 0% schema coverage), the description is inadequate. It lacks details on parameters, behavioral traits, error handling, and output, failing to provide enough context for safe and effective use by 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?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'existing CRM object' but doesn't explain the three parameters (objectType, objectId, properties) or their semantics (e.g., that objectType is an enum of CRM entities, objectId identifies the target, and properties holds the updates). This leaves key usage details unclear.
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 action ('Update') and resource ('existing CRM object'), which is clear but vague. It doesn't specify what fields can be updated or the scope of changes, and it doesn't differentiate from sibling tools like crm_update_company, crm_update_contact, or crm_batch_update_objects, which handle similar updates for specific object types or in batches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing object ID), exclusions, or compare to siblings like crm_update_company for company-specific updates or crm_batch_update_objects for bulk operations, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_archiveC
Archive (delete) an email record
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates this is a destructive operation ('delete'), but doesn't specify whether archiving is reversible, what permissions are required, or what happens to associated data. For a mutation tool with zero annotation coverage, this leaves significant gaps.
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 (4 words) and front-loaded with the essential action and resource. Every word earns its place with no redundancy or unnecessary elaboration.
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 destructive operation with no annotations, no output schema, and incomplete parameter documentation, the description is inadequate. It should explain more about the consequences of archiving, what 'archive' means in this context, and what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions no parameters, while the schema has one parameter (emailId) with 0% schema description coverage. Since the description doesn't add any parameter information beyond what's in the schema, it meets the baseline of 3 for having 0 parameters mentioned, but doesn't compensate for the lack of schema 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 clearly states the action ('Archive (delete)') and resource ('an email record'), making the purpose unambiguous. However, it doesn't differentiate this tool from its sibling 'emails_batch_archive', which appears to serve a similar function for multiple emails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'emails_batch_archive' for archiving multiple emails, or 'emails_update' for modifying instead of archiving. The description offers no context about prerequisites or appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_batch_archiveC
Archive (delete) multiple email records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| emailIds | Yes |
TDQS
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 indicates a destructive action ('Archive (delete)') but lacks critical details such as permission requirements, whether the operation is reversible, rate limits, error handling for invalid IDs, or what happens to archived emails. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. There is no wasted verbiage, and it directly communicates the tool's purpose without unnecessary elaboration, 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive batch operation), lack of annotations, no output schema, and 0% schema description coverage, the description is insufficient. It fails to address behavioral risks, parameter details, or expected outcomes, leaving significant gaps for an AI agent to understand and invoke the tool correctly in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description does not add any parameter-specific information beyond implying 'emailIds' are needed. It doesn't explain the format of email IDs, constraints on array size, or validation rules. With one parameter and no schema descriptions, the baseline is 3 as the description minimally hints at the parameter's role without providing meaningful semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and resource ('multiple email records') with the operational context ('in a single request'). It distinguishes from the singular 'emails_archive' sibling by specifying batch processing, though it doesn't explicitly contrast with other batch operations like 'emails_batch_read' or 'emails_batch_update'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., needing email IDs), compare it to the singular 'emails_archive', or specify scenarios where batch archiving is preferred over individual operations, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_batch_createC
Create multiple email records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but provides no information about permissions required, whether emails are actually sent or just stored, what happens on partial failures, rate limits, or response format. For a batch mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a basic tool description, though the brevity comes at the cost of completeness.
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 complex nested parameters (1 parameter with deep nesting), 0% schema description coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain the input structure, behavioral characteristics, error handling, or what constitutes successful creation, leaving critical gaps for the 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 schema has 0% description coverage, and the tool description provides no information about the 'inputs' parameter structure, required fields, or the complex nested objects for properties and associations. The description doesn't compensate for the complete lack of schema documentation, leaving the agent with no semantic understanding of how to construct valid input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple email records') and resource ('email records'), with the specific characteristic of batch processing ('in a single request'). It distinguishes from the singular 'emails_create' sibling tool by emphasizing batch capability, though it doesn't explicitly mention all sibling differences.
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 like 'emails_create' for single emails or other batch operations. It doesn't mention prerequisites, rate limits, or error handling for batch operations, leaving the agent with no contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_batch_readC
Read multiple email records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states this is a read operation (non-destructive) but doesn't cover rate limits, permissions needed, error handling for invalid IDs, response format, or pagination behavior. For a batch tool with complex nested parameters, this leaves significant gaps in understanding how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and uses clear terminology. Every word earns its place, making it easy to parse quickly while conveying the essential batch nature of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (batch operation with nested object parameters), lack of annotations, 0% schema description coverage, and no output schema, the description is inadequate. It doesn't explain the parameter structure, return values, error conditions, or behavioral constraints needed for effective use. For a tool with this level of parameter complexity, the description should provide much more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but fails to do so. It mentions 'multiple email records' but doesn't explain the 'inputs' parameter structure, what 'id' represents, what 'properties' and 'associations' arrays contain, or how to format requests. The description adds almost no semantic value beyond what's inferable from the parameter name 'inputs'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and resource ('multiple email records'), specifying it's a batch operation ('in a single request'). It distinguishes from individual read tools like 'emails_get' by emphasizing batch capability. However, it doesn't explicitly differentiate from other batch read tools like 'notes_batch_read' or 'products_batch_read' that follow similar patterns.
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. It doesn't mention when batch reading is preferable to individual reads ('emails_get'), when to use it versus listing/searching tools ('emails_list', 'emails_search'), or any prerequisites like authentication requirements. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_batch_updateC
Update multiple email records in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states this is an update operation (implies mutation) but doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, error handling for partial failures, or what the response looks like. For a batch mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized for a tool with a clear name, though the brevity comes at the cost of completeness. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch mutation tool with 1 parameter (complex nested array), 0% schema description coverage, no annotations, and no output schema, the description is severely incomplete. It doesn't explain the input structure, behavioral implications, error handling, or what constitutes a successful update. The agent would struggle to use this correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'multiple email records' which hints at an array structure, but provides no details about parameter format, required fields, or the meaning of properties like hs_email_status or hubspot_owner_id. The single sentence doesn't add meaningful semantic context beyond what's implied by the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update') and resource ('multiple email records'), and specifies it's a batch operation ('in a single request'). It distinguishes from non-batch email tools but doesn't explicitly differentiate from other batch operations like emails_batch_create or emails_batch_archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like emails_update (single update) or emails_batch_create (batch creation). It mentions 'multiple email records' which implies batch scenarios, but offers no explicit when/when-not guidance or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_createD
Create a new email record
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
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 but offers nothing beyond the basic 'create' action. It doesn't mention whether this requires authentication, what permissions are needed, whether it's idempotent, what happens on failure, rate limits, or any side effects. For a creation tool with complex nested parameters, this is critically insufficient.
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 at just four words, which is appropriately brief for what it does cover. However, this brevity comes at the cost of being severely under-specified rather than efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects, 16+ properties, associations), absence of annotations, lack of output schema, and 0% schema description coverage, the description is completely inadequate. It doesn't prepare an agent for what's required to successfully invoke this tool or what to expect in return.
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 0% schema description coverage and 2 parameters (one required), the description provides zero information about what parameters are needed or what they mean. The input schema shows complex nested objects with numerous properties and associations, but the description doesn't even hint at what data must be provided to create an email record.
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 'Create a new email record' is a tautology that essentially restates the tool name 'emails_create' without adding meaningful specificity. It doesn't distinguish this tool from sibling tools like 'emails_batch_create' or other creation tools in the system, nor does it specify what constitutes an 'email record' in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides absolutely no guidance about when to use this tool versus alternatives. With multiple sibling tools including 'emails_batch_create', 'emails_update', and various CRM creation tools, there's no indication of whether this is for single email creation, when batch operations might be preferable, or what prerequisites might exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_getC
Get details of a specific email
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Get details' implies a read-only operation, but it doesn't specify authentication requirements, rate limits, error behavior, or what happens when the emailId doesn't exist. For a retrieval tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. There's no wasted language or unnecessary elaboration. It's appropriately sized for a basic retrieval operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters (0% documented), no annotations, no output schema, and no sibling differentiation, the description is inadequate. It covers the basic purpose but leaves all parameters unexplained, provides no behavioral context, and offers no guidance on when to use it versus similar tools in the extensive sibling list.
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 0% schema description coverage for all 3 parameters, the description provides no information about what emailId should be, what properties can be requested, or what associations means. The description doesn't compensate for the complete lack of parameter documentation in the schema, leaving all parameters semantically undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('details of a specific email'), making the purpose immediately understandable. It distinguishes this from list/search operations by specifying 'specific email', though it doesn't explicitly differentiate from sibling email tools like emails_batch_read or emails_get (if that exists elsewhere).
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. It doesn't mention when to choose emails_get over emails_list, emails_search, emails_batch_read, or other retrieval methods. There's no context about prerequisites, error conditions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_listC
List all emails with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| after | No | ||
| properties | No | ||
| associations | No | ||
| archived | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'optional filtering' but doesn't describe pagination behavior (implied by 'limit' and 'after' parameters), rate limits, authentication requirements, or what 'list all' means in practice (e.g., time range, access restrictions). The description is insufficient for a tool with 5 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a list operation and front-loads the core purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain parameter usage, return format, pagination, or how filtering works. The agent would struggle to use this tool correctly without significant trial and error.
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 0%, so the description must compensate. It only mentions 'optional filtering' generically without explaining any of the 5 specific parameters (limit, after, properties, associations, archived). The description adds minimal value beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all emails with optional filtering' clearly states the verb ('List') and resource ('emails'), and specifies scope ('all' with 'optional filtering'). However, it doesn't distinguish from sibling 'emails_search' which likely provides more advanced search capabilities, keeping it from a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'emails_search' or 'emails_get'. The description mentions 'optional filtering' but doesn't specify what types of filtering are available or when to choose this over more targeted search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_searchC
Search emails with specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it searches with filters. It doesn't disclose critical behavioral traits like whether it's read-only, pagination behavior (implied by 'limit' and 'after' params but not explained), rate limits, authentication needs, or what happens on errors. This is inadequate for a search tool with complex parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, though this conciseness comes at the cost of completeness.
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 (5 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain parameter usage, behavioral expectations, or output format, making it insufficient for an AI agent to use the tool effectively beyond basic intent.
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 0%, so the description must compensate but only vaguely mentions 'specific filters'. It doesn't explain any of the 5 parameters (e.g., filterGroups structure, properties, limit, after, sorts) or their semantics, leaving them undocumented. This fails to add meaning beyond the bare 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 'Search emails with specific filters' clearly states the verb (search) and resource (emails), but it's vague about scope and doesn't distinguish from sibling tools like emails_list or emails_get. It specifies 'with specific filters' which adds some context but remains 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?
No guidance is provided on when to use this tool versus alternatives like emails_list or emails_search from other domains (e.g., crm_search_contacts). The description implies filtering is needed but doesn't specify scenarios or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
emails_updateC
Update an existing email record
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update an existing email record' implies a mutation operation, but it doesn't specify required permissions, whether the update is partial or full, what happens on success/failure, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence with no wasted words. It's front-loaded with the core action ('Update'), making it easy to parse. While brevity can lead to underspecification, in terms of structure and efficiency, this description earns full marks for being direct and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters with nested objects, 0% schema coverage, no annotations, no output schema), the description is inadequate. It doesn't explain the update behavior, parameter roles, expected outcomes, or error handling. For a mutation tool that modifies email records with multiple properties, this leaves the agent with insufficient information to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'update' and 'email record,' which loosely relates to the parameters (emailId and properties object), but it adds no specific meaning beyond what the schema provides. With 0% schema description coverage, the schema itself lacks descriptions for all parameters. The description doesn't compensate by explaining what emailId is, what properties can include, or the significance of required fields. Baseline 3 is appropriate as the schema defines structure, but value addition is minimal.
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 'Update an existing email record' clearly states the verb ('update') and resource ('email record'), but it's quite generic. It doesn't distinguish this tool from sibling tools like emails_batch_update or other update tools (calls_update, meetings_update, etc.), nor does it specify what aspects of an email can be updated. While the purpose is understandable, it lacks the specificity needed for optimal agent selection.
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 emails_batch_update, emails_create, and emails_archive available, the agent receives no indication about prerequisites (e.g., needing an existing emailId), when batch operations might be preferable, or what constitutes an 'existing email record.' This absence of context makes tool selection challenging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_archiveB
Archive (delete) an engagement
| Name | Required | Description | Default |
|---|---|---|---|
| engagementId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It indicates this is a destructive operation ('Archive (delete)'), which is helpful, but doesn't specify whether this is permanent or reversible deletion, what permissions are required, what happens to associated data, or what the response looks like. For a destructive tool with zero annotation coverage, this leaves significant behavioral gaps.
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 at just three words, with zero wasted language. It's front-loaded with the core action and resource, making it immediately understandable without unnecessary elaboration.
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 destructive tool with no annotations, no output schema, and minimal parameter documentation, the description is inadequate. It doesn't address critical aspects like the permanence of deletion, error conditions, authentication requirements, or what constitutes a valid engagementId. The context demands more comprehensive guidance for safe tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't explicitly mention parameters, but with only one parameter (engagementId) and 0% schema description coverage, the description's mention of 'an engagement' provides essential context that the parameter should be an engagement identifier. This compensates reasonably for the lack of schema documentation, though it doesn't specify format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and resource ('an engagement'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from sibling tools like 'calls_archive', 'emails_archive', or 'engagement_details_create', which would require mentioning it's specifically for engagement details rather than general engagements.
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. There's no mention of prerequisites (e.g., needing an existing engagement), when not to use it (e.g., for soft deletion vs permanent deletion), or how it differs from sibling tools like 'crm_archive_object' or 'engagement_details_update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_createC
Create a new engagement with details
| Name | Required | Description | Default |
|---|---|---|---|
| engagement | Yes | ||
| associations | No | ||
| metadata | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. 'Create' implies a write/mutation operation, but the description doesn't disclose behavioral traits like required permissions, whether this is idempotent, what happens on failure, rate limits, or what the response contains. For a creation tool with complex nested parameters, this is a significant gap.
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 at just 5 words. It's front-loaded with the core action and resource. There's zero wasted language, though this conciseness comes at the cost of completeness for such a complex 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 complexity (3 nested parameters, no output schema, no annotations), the description is inadequate. It doesn't explain what an 'engagement' is in this context, how it differs from other objects, what the creation response looks like, or any behavioral expectations. For a creation tool with such rich input structure, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no parameter descriptions. The description mentions 'with details' which vaguely hints at the three complex nested parameters (engagement, associations, metadata), but adds almost no semantic meaning about what these parameters represent, their relationships, or how they should be used. It doesn't compensate for the complete lack of schema 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 'Create a new engagement with details' states the basic action (create) and resource (engagement), but is vague about what 'with details' means. It doesn't distinguish this tool from sibling engagement tools like 'engagement_details_update' or 'crm_create_object' that might also handle engagements. The purpose is understandable but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools including 'engagement_details_update', 'crm_create_object', and various batch/create tools, the description offers no context about appropriate use cases, prerequisites, or distinctions from similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_getC
Get details of a specific engagement
| Name | Required | Description | Default |
|---|---|---|---|
| engagementId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Get' which implies a read operation, but doesn't disclose behavioral traits like whether it requires authentication, rate limits, error handling, or what the output looks like (e.g., JSON structure). This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded and efficiently conveys the core purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a read operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It doesn't cover behavioral aspects, parameter details, or output expectations, leaving significant gaps for an AI agent to understand how to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implies a single parameter ('engagementId') by mentioning 'a specific engagement', but doesn't add meaning beyond the schema's basic type/requirement. Since there's only one parameter, the baseline is 4, but it drops to 3 because it doesn't explain what an engagement ID is or its format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('details of a specific engagement'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'engagement_details_get_associated' or 'engagement_details_list', which would require mentioning it retrieves details for a single engagement by ID rather than associated engagements or a 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 no guidance on when to use this tool versus alternatives. It doesn't mention siblings like 'engagement_details_list' for multiple engagements or 'engagement_details_get_associated' for related data, nor does it specify prerequisites such as needing a valid engagement ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_get_associatedC
Get all engagements associated with an object
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| objectId | Yes | ||
| startTime | No | ||
| endTime | No | ||
| activityTypes | No | ||
| limit | No | ||
| offset | No |
TDQS
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 states a read operation ('Get'), implying it's likely non-destructive, but doesn't cover aspects like authentication needs, rate limits, pagination behavior (implied by limit/offset params but not explained), or error handling, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it front-loaded and easy to parse quickly. It directly states the core action without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 0% schema coverage, no annotations, no output schema), the description is inadequate. It lacks details on parameters, behavioral traits, output format, and usage context, making it incomplete for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but fails to do so. It mentions 'an object' but doesn't explain the 7 parameters (e.g., objectType, objectId, startTime, endTime, activityTypes, limit, offset) or their roles, leaving semantics undocumented beyond the schema's basic structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('engagements associated with an object'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'engagement_details_get' or 'engagement_details_list', which might retrieve engagements differently, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites, such as needing an existing object, and doesn't mention sibling tools like 'engagement_details_get' or 'engagement_details_list' for comparison, leaving usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_listC
List all engagements with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| startTime | No | ||
| endTime | No | ||
| activityTypes | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'optional filtering' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires authentication, pagination behavior (implied by limit/offset but not explained), rate limits, or what happens with large datasets. This leaves critical gaps for safe and effective use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('List all engagements'). There's no wasted verbiage, making it appropriately concise for a basic listing tool, though it could benefit from more detail given the complexity implied by parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with no schema descriptions, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain the return format, error conditions, or how filtering works, making it inadequate for an agent to use this tool confidently in a complex environment with many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters with 0% description coverage, and the description only vaguely mentions 'optional filtering' without explaining what parameters are available or their purposes (e.g., limit, offset, startTime, endTime, activityTypes). This fails to compensate for the schema's lack of documentation, leaving parameters largely undefined.
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 'List all engagements with optional filtering' clearly states the verb ('List') and resource ('engagements'), but it's vague about what 'engagements' specifically are in this context. It doesn't distinguish this tool from sibling tools like 'engagement_details_get' or 'engagement_details_get_associated', leaving ambiguity about scope and 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 no guidance on when to use this tool versus alternatives. With many sibling tools available (e.g., 'engagement_details_get', 'engagement_details_get_associated', 'calls_list', 'emails_list'), there's no indication of context, prerequisites, or comparisons to help an agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
engagement_details_updateC
Update an existing engagement's details
| Name | Required | Description | Default |
|---|---|---|---|
| engagementId | Yes | ||
| engagement | Yes | ||
| metadata | No |
TDQS
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. While 'Update' implies a mutation operation, the description doesn't address critical behavioral aspects: what permissions are required, whether the update is partial or complete, how validation works, what happens with invalid data, or what the response contains. For a mutation tool with complex nested parameters, this is a significant gap.
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 at just 5 words, with zero wasted language. It's front-loaded with the core action ('Update') and gets straight to the point without any unnecessary elaboration or repetition.
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 complex nested parameters (3 parameters including a deeply nested object), no annotations, and no output schema, the description is severely inadequate. It doesn't explain what constitutes valid updates, how the system handles partial versus complete updates, what permissions are required, or what the tool returns. The minimal description fails to provide the context needed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 3 parameters (including a complex nested 'engagement' object with 9 properties), the description provides no parameter information whatsoever. It doesn't explain what 'engagementId' refers to, what fields can be updated in the 'engagement' object, or what 'metadata' is for. The description fails to compensate for the complete lack of schema 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 clearly states the verb ('Update') and resource ('an existing engagement's details'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'engagement_details_create' or 'calls_update', which would require more specificity about what distinguishes engagement details updates from other update 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 no guidance on when to use this tool versus alternatives. With many sibling tools including 'engagement_details_create', 'engagement_details_get', and various batch operations, there's no indication of prerequisites, when this is appropriate versus creating new engagements, or how it relates to other engagement-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_archiveC
Archive (delete) a meeting
| Name | Required | Description | Default |
|---|---|---|---|
| meetingId | Yes |
TDQS
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 mentions 'archive (delete)', implying a destructive operation, but doesn't specify if this is permanent, reversible, requires specific permissions, or has side effects (e.g., affecting associated data). This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single phrase with no wasted words. It's front-loaded with the core action, making it easy to parse 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?
For a destructive tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permanence, permissions, or return values, which are critical for safe invocation. The simplicity of the parameter schema doesn't offset these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't add any parameter details beyond what the schema provides (a single 'meetingId' parameter). With 0% schema description coverage, the baseline is low, but since there's only one parameter and its purpose is implied by the tool name, the description doesn't compensate meaningfully. A score of 3 reflects minimal adequacy given the simple parameter structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('archive/delete') and resource ('a meeting'), making the purpose evident. However, it doesn't differentiate from sibling tools like 'meetings_batch_archive' or 'calls_archive', which would require specifying this is for single meetings only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'meetings_batch_archive' for multiple meetings or 'meetings_update' for modifications. The description lacks context about prerequisites, permissions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_batch_archiveC
Archive (delete) multiple meetings in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| meetingIds | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions 'Archive (delete)', implying a destructive mutation, but fails to specify permissions required, whether deletions are reversible, rate limits, or error handling for invalid IDs. This leaves significant gaps in understanding the tool's operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded and wastes no space, making it easy to parse 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?
For a destructive batch operation with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It doesn't cover critical aspects like return values, error conditions, or behavioral nuances, leaving the agent poorly informed about how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds no parameter details beyond implying 'meetingIds' are needed. It doesn't explain the format of IDs, array size limits, or validation rules. With one parameter, the baseline is 4, but the lack of any semantic clarification reduces this to 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and resource ('multiple meetings'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'meetings_archive' (single vs. batch) or 'calls_batch_archive' (meetings vs. calls), which prevents a perfect score.
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 like 'meetings_archive' for single meetings or other batch operations. It lacks context about prerequisites, such as needing meeting IDs, or exclusions, leaving the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_batch_createC
Create multiple meetings in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permissions required, whether it's idempotent, rate limits, error handling for partial failures, or what the response contains. This is inadequate for a batch mutation tool with complex nested parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the core functionality, making it easy to parse 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 tool's complexity (batch creation with nested objects), lack of annotations, 0% schema description coverage, and no output schema, the description is insufficient. It doesn't address behavioral aspects, parameter details, or expected outcomes, leaving significant gaps for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'multiple meetings' which hints at the 'inputs' array parameter, but doesn't explain the structure of meeting properties (like required fields 'hs_timestamp', 'hs_meeting_title', etc.) or the 'associations' field. This leaves critical parameter semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and resource ('multiple meetings'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'meetings_create' (single meeting creation) or 'meetings_batch_update' (batch updates), which would be needed for a perfect score.
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. It doesn't mention when batch creation is preferable to single creation ('meetings_create'), nor does it reference related batch operations like 'meetings_batch_update'. This leaves the agent without contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_batch_updateC
Update multiple meetings in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation (implying mutation) but provides no information about permissions required, whether updates are atomic, error handling for partial failures, rate limits, or what happens to unspecified meeting properties. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 7 words, with zero wasted language. It's front-loaded with the core action and immediately communicates the batch nature of the operation. Every word earns its place in this minimal description.
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 no annotations, 0% schema description coverage, no output schema, and complex nested parameters, the description is severely incomplete. It doesn't address critical aspects like authentication requirements, error conditions, response format, or how this tool differs from its single-update sibling. The agent would struggle to use this tool correctly based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 1 parameter (a complex array of objects), the description provides almost no parameter information. It mentions 'multiple meetings' which hints at the array structure, but doesn't explain the required 'id' and 'properties' fields, the specific meeting properties that can be updated, or the enum values for 'hs_meeting_outcome'. The description fails to compensate for the complete lack of schema 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 clearly states the verb ('update') and resource ('multiple meetings'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'meetings_update' or explain what 'batch' means in this context, which prevents a perfect score.
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 the single 'meetings_update' tool or other batch operations. It mentions 'in a single request' but doesn't explain the advantages, limitations, or appropriate scenarios for batch updates versus individual updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_createD
Create a new meeting
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
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 but fails completely. It doesn't mention that this is a write operation requiring permissions, doesn't describe what happens upon creation (e.g., returns a meeting ID), doesn't warn about required fields, and provides no information about rate limits, error conditions, or system behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just three words. While this represents severe under-specification, from a pure conciseness perspective it's front-loaded with zero wasted words and no structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters with nested objects, no output schema, no annotations), the description is completely inadequate. It doesn't explain what the tool returns, what permissions are needed, how to structure the complex input, or provide any context about the meeting creation process in the broader system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the parameters are documented in the schema. The description adds no information about the 2 top-level parameters ('properties' and 'associations') or their complex nested structures. For a tool with 2 parameters and rich nested objects, this leaves the agent completely in the dark about what data to provide.
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 'Create a new meeting' is essentially a tautology that restates the tool name 'meetings_create' without adding meaningful specificity. It doesn't distinguish this tool from sibling tools like 'meetings_batch_create' or 'calls_create', nor does it clarify what kind of meeting is being created or in what context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description provides no context about prerequisites, when this tool is appropriate versus batch operations, or what distinguishes it from other creation tools in the sibling list like 'calls_create' or 'tasks_create'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_getC
Get details of a specific meeting
| Name | Required | Description | Default |
|---|---|---|---|
| meetingId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
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 implies a read-only operation ('Get') but doesn't specify permissions, rate limits, error handling, or what the output looks like (e.g., format, included fields). This leaves significant gaps for an AI agent to understand how to use it 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 a single, straightforward sentence with no wasted words. It's front-loaded with the core purpose, making it easy to parse quickly, though this conciseness comes at the cost of detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no output schema, no annotations), the description is insufficient. It lacks details on parameters, behavioral traits, and output, making it incomplete for safe and effective use by an AI agent. It relies too heavily on the schema without descriptive support.
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 0%, so the description must compensate, but it adds no parameter information. It doesn't explain what 'meetingId', 'properties', or 'associations' mean, their formats, or how they affect the output. This is inadequate for a tool with 3 parameters, one required.
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 verb ('Get') and resource ('details of a specific meeting'), which is clear but basic. It doesn't differentiate from sibling tools like 'meetings_list' or 'meetings_search' that also retrieve meeting information, nor does it specify what 'details' include beyond the schema parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention that this is for retrieving a single meeting by ID, unlike 'meetings_list' for multiple meetings or 'meetings_search' for filtered queries. There's no context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_listC
List all meetings with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | ||
| limit | No | ||
| createdAfter | No | ||
| createdBefore | No | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'optional filtering' but doesn't describe key behaviors like whether this is a read-only operation, if it requires authentication, how results are paginated (implied by 'limit' but not explained), or potential rate limits. For a list tool with 5 parameters, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence: 'List all meetings with optional filtering'. It's front-loaded with the core action and resource, and there's no wasted verbiage. Every word earns its place, making it efficient to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain parameter meanings, behavioral traits like pagination or safety, or how it differs from sibling tools. For a list operation with multiple filtering options, this minimal description leaves too many gaps for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The description only vaguely mentions 'optional filtering' without explaining what parameters are available (e.g., 'after', 'limit', 'createdAfter', 'createdBefore', 'properties') or their purposes. It fails to compensate for the lack of schema documentation, leaving parameters largely undocumented.
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 'List all meetings with optional filtering' clearly states the verb ('List') and resource ('meetings'), making the basic purpose understandable. However, it's somewhat vague about what 'meetings' entails (e.g., type, scope) and doesn't differentiate from sibling tools like 'meetings_search' or 'meetings_get', which likely serve related purposes. It avoids tautology but lacks specificity.
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 siblings like 'meetings_search', 'meetings_get', and 'meetings_list' (if this is a duplicate or similar), there's no indication of differences in filtering capabilities, performance, or use cases. This leaves the agent without direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_searchC
Search meetings with specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'search' and 'filters' but doesn't describe whether this is a read-only operation, what permissions are required, how results are returned (e.g., pagination with 'limit' and 'after'), or any rate limits. For a search tool with 5 parameters and no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's appropriately sized and front-loaded, stating the core action immediately. Every word earns its place, making it highly concise and well-structured for its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters with nested structures like 'filterGroups' and 'sorts'), 0% schema description coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain how to construct filters, what properties are available, how sorting works, or what the return format is. This leaves critical gaps for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 5 parameters are documented in the schema. The description only vaguely references 'specific filters', which partially hints at 'filterGroups' but doesn't explain the other parameters ('properties', 'limit', 'after', 'sorts') or their relationships. It adds minimal value beyond the schema, failing to compensate for the coverage gap.
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 'Search meetings with specific filters' states the verb ('search') and resource ('meetings'), but it's vague about what constitutes 'specific filters' and doesn't distinguish this tool from sibling tools like 'meetings_list' or 'meetings_get'. It provides a basic purpose but lacks specificity about scope or differentiation from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'meetings_list' (which might list all meetings without filters) or 'meetings_get' (which retrieves a single meeting). The description implies filtering but doesn't specify use cases, prerequisites, or exclusions, leaving the agent to guess based on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
meetings_updateC
Update an existing meeting
| Name | Required | Description | Default |
|---|---|---|---|
| meetingId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update an existing meeting' implies a mutation operation but reveals nothing about permissions required, whether changes are reversible, rate limits, error conditions, or what happens to unspecified properties. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a basic tool description and front-loads the core purpose immediately.
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 2 parameters (including a complex nested object), 0% schema description coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain what can be updated, how to identify meetings, what the response looks like, or any behavioral constraints. The description fails to provide the necessary context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the parameters have descriptions in the schema. The tool description adds no information about what 'meetingId' or 'properties' represent, nor does it explain the nested properties object with fields like 'hs_meeting_title' or 'hs_meeting_outcome'. The description fails to compensate for the complete lack of schema 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 'Update an existing meeting' clearly states the verb ('Update') and resource ('an existing meeting'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'meetings_batch_update' or 'meetings_create', which would be necessary for a perfect score.
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. There's no mention of prerequisites (e.g., needing a meetingId), when to use batch updates instead, or how this differs from 'meetings_create'. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_archiveC
Archive (delete) a note
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes |
TDQS
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 states the tool archives/deletes a note, implying a destructive mutation, but lacks critical details: whether archiving is reversible, what permissions are required, if it affects associated data, or what the response looks like. The parenthetical '(delete)' adds some clarity but is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single phrase with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly, though this brevity contributes to gaps in other dimensions.
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 destructive mutation tool with no annotations, no output schema, and minimal parameter documentation, the description is inadequate. It doesn't cover behavioral implications, error conditions, or usage context, leaving significant gaps for an AI agent to understand how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't explicitly mention parameters, but with only one parameter (noteId) and 0% schema description coverage, it implicitly suggests the tool acts on a specific note. Since there are zero parameters described in the schema, the baseline is 4, as the description at least implies the need for a note identifier without adding unnecessary detail.
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 'Archive (delete) a note' clearly states the action (archive/delete) and resource (note), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'notes_batch_archive' or 'notes_update', nor does it explain what 'archive' means specifically in this context versus deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing note), compare to batch operations like 'notes_batch_archive', or indicate when archiving is appropriate versus updating or deleting through other means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_batch_archiveC
Archive (delete) multiple notes in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| noteIds | Yes |
TDQS
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 states the tool archives/deletes notes, implying a destructive mutation, but lacks details on permissions, reversibility, rate limits, or response format. The mention of 'single request' hints at efficiency but doesn't clarify batch size limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. There is no wasted verbiage, and it directly communicates the tool's purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, lack of annotations, 0% schema coverage, and no output schema, the description is insufficient. It doesn't address critical aspects like safety warnings, input validation, or what happens post-archive, leaving significant gaps for an AI agent to operate safely.
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 0%, so the description must compensate for undocumented parameters. It mentions 'multiple notes' but doesn't explain the 'noteIds' parameter's format, constraints, or expected values. No additional semantic context is provided beyond what's implied by the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('archive/delete') and resource ('multiple notes') with the scope 'in a single request.' It distinguishes from sibling 'notes_archive' by specifying batch capability, though it doesn't explicitly contrast with other batch operations like 'notes_batch_create' or 'notes_batch_update.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'notes_archive' for single notes or other batch operations. The description implies batch deletion but doesn't specify prerequisites, limitations, or contextual triggers for choosing this method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_batch_createC
Create multiple notes in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but provides almost none. It states this is a creation operation but doesn't mention permissions required, whether this is a write operation (implied but not stated), rate limits, error handling, what happens on partial failures, or any other behavioral characteristics. The single sentence offers no transparency beyond the basic action.
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 maximally concise with a single sentence that communicates the core functionality. There's no wasted language, repetition, or unnecessary elaboration. It's front-loaded with the essential information, though this conciseness comes at the cost of completeness.
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 complex nested parameters (0% schema coverage), no annotations, and no output schema, the description is completely inadequate. It doesn't explain what data notes contain, how associations work, what permissions are needed, what the response looks like, or any error conditions. The single sentence fails to provide the context needed for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 1 parameter (a complex nested array), the description provides zero information about parameters. It doesn't mention the 'inputs' parameter at all, doesn't explain the structure of note objects, required fields like 'hs_note_body', or the associations system. The description fails to compensate for the complete lack of schema 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 clearly states the action ('Create multiple notes') and resource ('notes'), making the purpose immediately understandable. It distinguishes from the singular 'notes_create' sibling by specifying batch operations, though it doesn't explicitly contrast with other batch operations like 'notes_batch_update' or 'notes_batch_archive'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when batch creation is preferable to individual creation, doesn't reference sibling tools like 'notes_create' or 'notes_batch_update', and offers no context about prerequisites, limitations, or appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_batch_readC
Read multiple notes in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a read operation without disclosing behavioral traits like rate limits, authentication needs, error handling, or what happens with invalid IDs. It mentions 'multiple notes' but doesn't specify limits or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and context, making it easy to parse quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch read tool with 1 parameter (complex nested array), 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain input structure, return values, error cases, or operational constraints, leaving significant gaps for agent understanding.
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 0%, so the description must compensate but adds no parameter information. It doesn't explain what 'inputs' contains, the required 'id' field, optional 'properties' and 'associations' arrays, or their purposes. The description fails to provide meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Read') and resource ('multiple notes'), and specifies the operational context ('in a single request'). However, it doesn't differentiate from sibling tools like 'notes_get' (single note read) or 'notes_list' (list all notes), which would require explicit comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'notes_get' for single notes or 'notes_list' for bulk listing. The description implies batch operations but doesn't specify thresholds, prerequisites, or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_batch_updateC
Update multiple notes in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's an update operation. It lacks critical behavioral details: whether this is atomic/partial, permission requirements, rate limits, error handling for invalid inputs, or what happens to existing note properties not mentioned. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and scope, making it easy to parse 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?
For a batch mutation tool with 1 parameter (complex nested array), 0% schema description coverage, no annotations, and no output schema, the description is incomplete. It misses essential context like input format, behavioral constraints, and expected outcomes, leaving significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds no parameter information. It doesn't explain the 'inputs' array structure, required fields like 'id' and 'properties', or the specific properties (hs_note_body, hs_timestamp, hubspot_owner_id) that can be updated. The baseline would be 3 if schema coverage were high, but here it's low with no compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('multiple notes'), and specifies the scope ('in a single request'). It distinguishes from individual update operations but doesn't explicitly differentiate from sibling batch tools for other resources like calls or emails, which would require a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'notes_update' (for single updates) or other batch operations. The description implies batch efficiency but doesn't state prerequisites, limitations, or trade-offs compared to single updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_createC
Create a new note
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
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 states 'Create a new note', implying a write operation, but doesn't mention permissions, side effects, or response format. This is a significant gap for a mutation tool, as the agent lacks context on what happens upon invocation.
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 a single sentence, 'Create a new note', which is front-loaded and wastes no words. While it may be under-specified, it earns full marks for brevity and clarity within its limited scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters with nested objects, 0% schema coverage, no annotations, and no output schema), the description is incomplete. It doesn't address parameter meanings, behavioral traits, or output, making it inadequate for the agent to use the tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the schema provides no descriptions for the 2 parameters. The description adds no information about parameters, failing to compensate for this gap. It doesn't explain what 'properties' or 'associations' mean, leaving the agent to guess based on property names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new note' clearly states the action (create) and resource (note), which is adequate for basic understanding. However, it doesn't differentiate from sibling tools like 'notes_batch_create' or specify what kind of note (e.g., CRM note, engagement note), making it somewhat vague compared to more specific alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'notes_batch_create' or 'engagement_details_create'. The description lacks context about prerequisites, such as required associations or ownership, leaving the agent to infer usage from the schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_getC
Get details of a specific note
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Get details' implying a read operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error conditions, or what 'details' includes (e.g., full content vs metadata). This leaves significant gaps for a tool with 3 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose, making it easy to parse 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?
For a tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain parameter usage, return values, or behavioral context, leaving the agent poorly equipped to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'specific note' hinting at 'noteId', but doesn't explain 'properties' or 'associations' parameters. With 3 parameters and no schema descriptions, the description adds minimal value beyond the obvious.
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 'Get details of a specific note' clearly states the verb ('Get') and resource ('note'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'notes_list' or 'notes_search' that also retrieve note information, preventing a perfect score.
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 siblings like 'notes_list' for multiple notes and 'notes_search' for filtered retrieval, the agent must infer usage based on the 'specific note' phrasing, which is insufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_listC
List all notes with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| after | No | ||
| properties | No | ||
| associations | No | ||
| archived | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a list operation but doesn't mention pagination behavior (implied by 'after' parameter), rate limits, authentication requirements, whether it returns archived notes by default, or what the response format looks like. The mention of 'optional filtering' is vague about implementation details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with no wasted words. It's appropriately sized for a list operation and front-loads the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, 0% schema description coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain the filtering mechanism, pagination approach, response format, or how this differs from other note-related tools. The agent would struggle to use this tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for 5 parameters, the description must compensate but only vaguely mentions 'optional filtering' without explaining what parameters control filtering. It doesn't clarify the meaning of 'limit', 'after', 'properties', 'associations', or 'archived' parameters, leaving significant gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all notes with optional filtering' clearly states the verb ('List') and resource ('notes'), and specifies scope ('all notes') with capability ('optional filtering'). It doesn't distinguish from sibling tools like notes_search or notes_get, but provides a complete basic purpose statement.
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 like notes_search, notes_get, or notes_batch_read. It mentions 'optional filtering' but doesn't explain what types of filtering are available or when filtering would be appropriate versus using a search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_searchD
Search notes with specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
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 but provides almost none. 'Search notes with specific filters' doesn't indicate whether this is a read-only operation, whether it has side effects, what authentication might be required, rate limits, pagination behavior (though the schema has 'limit' and 'after' parameters), or what the output looks like. For a search tool with complex filtering capabilities, this minimal description fails to provide essential behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words. While this brevity comes at the cost of completeness, it's efficiently structured with zero wasted words. The single sentence directly states the core function without unnecessary elaboration, making it front-loaded and easy to parse despite its inadequacy in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (5 parameters with nested objects, complex filtering logic, sorting, pagination) and the complete absence of both annotations and output schema, the description is woefully incomplete. 'Search notes with specific filters' doesn't prepare an agent for the sophisticated filtering system with multiple operators, property-based queries, or the pagination mechanism. For a tool with this level of parameter complexity and no structured documentation elsewhere, the description provides almost no useful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, meaning none of the 5 parameters have descriptions in the schema. The tool description 'Search notes with specific filters' only vaguely hints at the 'filterGroups' parameter but provides no meaningful semantic information about any parameters. It doesn't explain what 'properties' returns, what 'sorts' does, how 'limit' and 'after' work for pagination, or the complex filter structure with operators and property names. The description fails to compensate for the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search notes with specific filters' is a tautology that essentially restates the tool name 'notes_search'. It provides the basic verb+resource ('search notes') but lacks specificity about what kind of search this performs or how it differs from other note-related tools like 'notes_list' or 'notes_get' in the sibling list. The description doesn't distinguish this tool from its siblings beyond the obvious name difference.
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 absolutely no guidance on when to use this tool versus alternatives. With multiple note-related tools available (notes_list, notes_get, notes_search, notes_create, notes_update, etc.), the agent receives no indication about what makes this search tool appropriate for certain scenarios or what its limitations might be. There's no mention of prerequisites, typical use cases, or comparison to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes_updateC
Update an existing note
| Name | Required | Description | Default |
|---|---|---|---|
| noteId | Yes | ||
| properties | Yes |
TDQS
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. 'Update an existing note' implies a mutation operation, but it doesn't specify whether this requires specific permissions, what happens to unspecified properties (partial vs. full updates), whether changes are reversible, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise ('Update an existing note') with no wasted words, making it front-loaded and easy to parse. Every word earns its place, though this brevity comes at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mutation tool with 2 required parameters, nested objects, 0% schema coverage, no annotations, and no output schema), the description is insufficient. It doesn't explain what properties can be updated, how to format them, what the response looks like, or error conditions. For a tool that modifies data, this leaves critical gaps 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 schema description coverage is 0%, meaning neither parameter ('noteId' and 'properties') has descriptions in the schema. The tool description adds no information about what these parameters mean, their expected formats, or how 'properties' relates to note fields like 'hs_note_body'. With two required parameters and nested objects, the description fails to compensate for the lack of schema 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 'Update an existing note' clearly states the verb ('Update') and resource ('an existing note'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'notes_batch_update' or 'notes_update' (if there were multiple note update tools), though in this context 'notes_update' appears to be the primary update tool for individual notes.
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 like 'notes_batch_update' or 'notes_create'. It doesn't mention prerequisites (e.g., needing an existing note ID) or contextual constraints, leaving the agent to infer usage from the tool name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_archiveC
Move an Object identified by ID to the recycling bin.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the action is destructive (moving to recycling bin implies deletion or archiving), but lacks details on permissions required, reversibility, side effects, or rate limits. For a mutation tool, this is a significant gap in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and target, making it easy to parse quickly. Every word contributes directly to the tool's 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?
For a destructive mutation tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks details on behavioral traits, parameter usage, and expected outcomes. Given the complexity and sibling tools, more context is needed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'ID' as the identifier, which aligns with the 'productId' parameter, but doesn't explain format, constraints, or where to find the ID. With one undocumented parameter, the description adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move') and target ('Object identified by ID'), specifying it goes 'to the recycling bin.' It distinguishes from siblings like products_batch_archive by focusing on single-object archiving, though it doesn't explicitly name alternatives. The purpose is specific but could be more precise about the object type (e.g., 'product').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like products_batch_archive or other archive tools (e.g., crm_archive_object). The description implies it's for archiving a single product, but it doesn't specify prerequisites, exclusions, or contextual cues for selection among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_batch_archiveC
Archive (delete) a batch of products by ID
| Name | Required | Description | Default |
|---|---|---|---|
| productIds | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool archives/deletes products, implying a destructive mutation, but doesn't clarify if archiving is reversible, what permissions are required, whether it's synchronous/asynchronous, or what happens on partial failure. This leaves significant gaps for a destructive 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 a single, efficient sentence that immediately conveys the core functionality without unnecessary words. It's front-loaded with the key action and resource, making it easy to parse 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?
For a destructive batch operation with no annotations and no output schema, the description is inadequate. It doesn't explain what 'archive' means operationally, whether it's soft/hard delete, what confirmation is needed, error handling, or return values. The context signals show this is a mutation tool requiring more behavioral disclosure.
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 0%, so the description must compensate. It mentions 'by ID' which clarifies the 'productIds' parameter's purpose, but doesn't specify ID format, maximum batch size, or validation rules. This provides basic context but leaves important details undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive (delete)') and resource ('a batch of products by ID'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'products_archive' (which likely archives single products), missing full sibling distinction.
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 like 'products_archive' (for single products) or 'products_batch_update' (for modifying instead of archiving). It mentions no prerequisites, constraints, or recommended contexts for batch archiving.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_batch_createC
Create a batch of products
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action without disclosing behavioral traits. It doesn't mention whether this is a mutating operation (implied but not explicit), what permissions are required, how errors are handled in batch contexts, rate limits, or what happens on partial failures. The description adds no behavioral context beyond the basic verb.
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 maximally concise with just four words that directly convey the core function. There's no wasted language or unnecessary elaboration, making it easy to parse 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?
For a batch creation tool with 0% schema description coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain the batch semantics (atomicity, error handling), required fields, validation rules, or what the tool returns. The context demands much more information than provided.
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 0%, so the description must compensate but provides no parameter information. The single parameter 'inputs' (an array of product objects) and its nested structure (properties like name, price, sku) are completely undocumented in the description. The description adds zero semantic value beyond what's visible in the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('batch of products'), making the purpose immediately understandable. It distinguishes from sibling 'products_create' by specifying batch operation, though it doesn't explain what differentiates it from other batch operations like 'products_batch_update' beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'products_create' for single products or 'products_batch_update' for modifications. The description doesn't mention prerequisites, constraints, or typical use cases for batch creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_batch_readC
Read a batch of products by internal ID, or unique property values. Retrieve records by the idProperty parameter to retrieve records by a custom unique value property.
| Name | Required | Description | Default |
|---|---|---|---|
| propertiesWithHistory | Yes | ||
| idProperty | No | ||
| productIds | Yes | ||
| properties | Yes |
TDQS
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 describes a read operation (implied safe/non-destructive) but lacks details on permissions, rate limits, error handling, or response format. The mention of retrieving records by custom unique values adds some context, but overall behavioral traits are under-specified 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 concise (two sentences) and front-loaded with the main purpose. However, the second sentence is somewhat redundant with the first and could be more efficiently integrated. While not wasteful, it lacks the precision of top-tier descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (batch operation with 4 parameters, 3 required), 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain parameter interactions, expected output, error conditions, or how this differs from similar sibling tools, leaving significant gaps 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?
Schema description coverage is 0%, so the description must compensate for all 4 parameters. It only mentions 'idProperty' for custom unique values, leaving 'propertiesWithHistory', 'productIds', and 'properties' unexplained. This provides minimal semantic value beyond the bare schema, failing to clarify what these arrays contain or how they interact.
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: reading a batch of products by internal ID or unique property values. It specifies the verb ('Read'), resource ('products'), and scope ('batch'), but doesn't explicitly differentiate from sibling tools like 'products_read' or 'products_list' beyond mentioning batch retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance, mentioning the 'idProperty' parameter for custom unique values but not explaining when to use this tool versus alternatives like 'products_read' (single product) or 'products_list' (list with filters). No explicit when/when-not scenarios or prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_batch_updateC
Update a batch of products by internal ID, or unique values specified by the idProperty query param.
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
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 states this is an update operation (implying mutation) but doesn't cover critical aspects like required permissions, whether changes are reversible, rate limits, error handling for partial failures in batch updates, or what the response looks like. For a batch mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point without unnecessary words. It's appropriately sized for the tool's complexity, though it could benefit from additional context in subsequent sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch update tool with no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't address mutation behavior, error handling, permissions, response format, or how to structure the 'inputs' array properly. Given the complexity of batch operations, more guidance is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'idProperty' as a query param for alternative identification, but doesn't explain the 'inputs' array structure, the 'id' field, the 'properties' object with its nested fields (name, description, price, etc.), or the 'objectWriteTraceId'. The description adds minimal value beyond what's implied by the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('batch of products'), and specifies the identification method ('by internal ID, or unique values specified by the `idProperty` query param'). However, it doesn't explicitly differentiate from sibling tools like 'products_update' (single update) or 'products_batch_create' (batch creation), which would be needed for a perfect score.
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 like 'products_update' for single updates or 'products_batch_create' for batch creation. It mentions the 'idProperty' parameter but doesn't explain when to use it versus internal ID, nor does it mention prerequisites or error handling for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_createC
Create a product with the given properties and return a copy of the object, including the ID.
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions the creation action and return format, but fails to address critical aspects like required permissions, potential side effects (e.g., if creation affects other data), rate limits, or error handling. This leaves significant gaps in understanding how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the core action and outcome without unnecessary details. It is front-loaded with the main purpose, making it easy for an agent to parse 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 complexity of a creation tool with no annotations, a nested parameter object, and no output schema, the description is insufficient. It lacks details on behavioral traits, parameter meanings, error responses, and how it fits among sibling tools, making it incomplete for safe and effective use by 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% description coverage, with one required parameter 'properties' that is a nested object containing fields like name and price. The description does not explain these parameters or their semantics beyond implying they are 'given properties.' Since schema coverage is low, the description adds minimal value, but it at least hints at the parameter's role in product creation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a product') and specifies what is returned ('return a copy of the object, including the ID'), which distinguishes it from other product-related tools like products_list or products_read. However, it does not explicitly differentiate from sibling tools like products_batch_create, which might handle multiple products.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as products_batch_create for multiple products or other CRUD operations. It lacks context about prerequisites, error conditions, or specific use cases, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_listB
Read a page of products. Control what is returned via the properties query param. after is the paging cursor token of the last successfully read resource will be returned as the paging.next.after JSON property of a paged response containing more results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| after | No | ||
| properties | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses pagination behavior ('Read a page of products', 'after is the paging cursor token') and mentions the response structure ('paging.next.after JSON property'). However, it doesn't address rate limits, authentication requirements, error conditions, or whether this is a safe read operation (though implied by 'Read').
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 with two sentences. The first sentence states the core purpose, and the second explains parameter usage and response behavior. There's no wasted text, though the second sentence is somewhat dense and could be structured more clearly.
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 paginated list tool with 3 parameters, 0% schema coverage, and no output schema, the description provides adequate but incomplete context. It covers pagination mechanics and parameter purposes but lacks details about response format beyond cursor tokens, error handling, or performance characteristics. Given the complexity, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context for all three parameters beyond the 0% schema coverage. It explains that 'properties' controls what is returned, and 'after' is a paging cursor token that appears in the response. While it doesn't detail 'limit' or provide format specifics, it gives functional understanding that compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a page of products, specifying the verb ('Read') and resource ('products'). It distinguishes from siblings like products_create or products_update by focusing on listing rather than creating/modifying. However, it doesn't explicitly differentiate from products_search or products_read, which might have overlapping 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 no guidance on when to use this tool versus alternatives like products_search or products_read. It mentions controlling returned properties via the 'properties' parameter but doesn't explain when this paginated list approach is preferred over search or direct read operations. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_readC
Read an Object identified by ID
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Read', implying a read-only operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or what happens if the ID doesn't exist. For a tool with 3 parameters and no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, front-loaded with the core action. There's no wasted text, making it easy to parse quickly. However, this brevity contributes to underspecification in other dimensions.
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 3 parameters with 0% schema coverage, no annotations, no output schema, and many sibling tools, the description is incomplete. It doesn't explain return values, error conditions, or how parameters affect the read operation. For a read tool in a complex environment, this leaves too much undefined for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'ID' which maps to 'productId', but doesn't explain 'properties' or 'associations' parameters. With 3 parameters total, the description adds minimal meaning beyond the schema, failing to clarify what these arrays control or their expected formats.
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 verb ('Read') and resource ('Object identified by ID'), which provides a basic purpose. However, it's vague about what type of object (product) and doesn't differentiate from sibling tools like 'products_batch_read' or 'crm_get_object'. The name 'products_read' suggests products, but the description uses generic 'Object', creating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools (e.g., 'products_batch_read', 'products_list', 'crm_get_object'), the description lacks context about use cases, prerequisites, or comparisons. It implies single-object retrieval but doesn't specify when batch or list tools might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_searchD
Search products
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| limit | No | ||
| after | No | ||
| sorts | No | ||
| properties | No | ||
| filterGroups | Yes |
TDQS
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 but fails completely. It doesn't indicate whether this is a read-only operation, whether it has side effects, what authentication might be required, or any rate limits. For a search tool with 6 parameters and complex filtering capabilities, this lack of behavioral information is a significant gap.
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?
While technically concise with just two words, this represents under-specification rather than effective conciseness. The description is front-loaded but provides so little information that it fails to serve its purpose. Every word should earn its place, but here the words don't provide enough value to justify their inclusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters with nested objects, no output schema, no annotations), the description is completely inadequate. It doesn't explain the tool's purpose beyond the name, provides no parameter guidance, offers no behavioral context, and gives no indication of what the search returns. For a tool with this level of complexity, the description fails to provide even basic contextual information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for all 6 parameters, the description provides zero information about what the parameters mean or how to use them. The schema shows complex filtering capabilities (filterGroups with operators, sorts, properties, etc.), but the description doesn't even hint at these capabilities. The description fails to compensate for the complete lack of schema 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 'Search products' is a tautology that merely restates the tool name without adding specificity. It doesn't clarify what kind of search this performs (full-text, filtered, etc.) or what resource scope it covers. While it does include the verb 'search' and resource 'products', it lacks the differentiation needed to distinguish it from other product-related tools like products_list or products_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides absolutely no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for usage, or comparison to sibling tools like products_list. The agent receives no help in determining when this search tool is appropriate versus other product-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
products_updateC
Perform a partial update of an Object identified by ID. Read-only and non-existent properties will result in an error. Properties values can be cleared by passing an empty string.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behavioral traits: partial update nature, ID requirement, error conditions for read-only/non-existent properties, and that empty strings clear values. However, it lacks information about permissions, rate limits, side effects, or response format, which are important for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences that convey core functionality and important constraints. No wasted words, though it could be slightly more comprehensive given the lack of annotations and schema descriptions.
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 2 parameters (including a nested object), 0% schema description coverage, no annotations, and no output schema, the description is insufficient. It covers basic operation but lacks details about parameter meanings, error handling beyond two specific cases, return values, and integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'ID' and 'properties' but doesn't explain what 'productId' represents, what specific properties can be updated, or the structure of the properties object. The description adds minimal value beyond what's evident from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'partial update of an Object identified by ID', specifying the verb (partial update), resource (Object), and identifier (ID). However, it doesn't explicitly differentiate from sibling tools like 'products_update' vs 'products_batch_update' or 'products_create', though the 'partial update' wording implies distinction from full replacement 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 no guidance on when to use this tool versus alternatives like 'products_create', 'products_batch_update', or 'products_read'. It mentions error conditions (read-only and non-existent properties) but doesn't specify prerequisites, appropriate contexts, or comparison to sibling tools in the extensive list provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_archiveC
Archive (delete) a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'archive (delete)' which implies a destructive operation, but doesn't clarify if this is permanent deletion, soft deletion, reversible, or what permissions are required. No information about rate limits, side effects, or response format is included.
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 at just three words, front-loading the essential information with zero wasted text. Every word earns its place by specifying both the action and target resource.
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 destructive operation tool with no annotations, no output schema, and incomplete parameter documentation, the description is inadequate. It should address critical behavioral aspects like permanence, reversibility, permissions, and what happens to associated data when a task is archived.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't mention the 'taskId' parameter at all, and with 0% schema description coverage, the schema provides no parameter documentation either. However, since there's only one required parameter and its purpose is reasonably inferable from the tool name, the baseline of 3 is appropriate despite the lack of explicit parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('archive (delete)') and resource ('a task'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'tasks_batch_archive', which handles multiple tasks, leaving some ambiguity about when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'tasks_batch_archive' for multiple tasks or 'tasks_update' for modifying instead of archiving. The description lacks context about prerequisites, permissions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_batch_archiveC
Archive (delete) multiple tasks in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| taskIds | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the destructive nature ('archive (delete)') which is critical, but lacks other behavioral traits: no information about permissions needed, whether deletion is permanent or reversible, rate limits, error handling for partial failures, or what the response looks like. For a destructive batch operation with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('archive (delete)') and key qualification ('multiple tasks in a single request'). Every word earns its place with zero redundancy or unnecessary elaboration.
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 destructive batch operation with 1 parameter, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It covers the basic purpose but misses critical context: parameter details, behavioral implications (permanence, permissions), error handling, and response format. The agent would struggle to use this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'multiple tasks' which implies the 'taskIds' parameter, but provides no semantic details: no format requirements for task IDs, no constraints on array size, no examples, and no explanation of what constitutes valid task IDs. The description adds minimal value beyond what's inferable from the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('archive (delete)') and resource ('multiple tasks'), and specifies the scope ('in a single request'). It distinguishes from the singular 'tasks_archive' sibling by indicating batch operation. However, it doesn't explicitly differentiate from other batch archive tools like 'calls_batch_archive' or 'notes_batch_archive' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., required permissions), when to use batch vs individual archive ('tasks_archive'), or any limitations (e.g., maximum number of tasks per batch). It simply states what the tool does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_batch_createC
Create multiple tasks in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
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 states the tool creates tasks but doesn't mention permissions required, rate limits, error handling for partial failures, or what the response contains. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It is appropriately sized and front-loaded, clearly stating the core functionality without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested schema with multiple properties and associations), lack of annotations, and no output schema, the description is incomplete. It fails to explain critical aspects like input format, behavioral traits, or expected outcomes, leaving the agent with insufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'multiple tasks' but provides no details on the 'inputs' parameter structure, required fields, or the nested 'properties' and 'associations' objects. The description adds minimal value beyond the schema's existence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create multiple tasks') and the method ('in a single request'), which is specific and distinguishes it from the singular 'tasks_create' sibling tool. However, it doesn't explicitly mention the resource domain (e.g., CRM tasks) or differentiate from other batch operations like 'tasks_batch_update' beyond the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'tasks_create' for single tasks or 'tasks_batch_update' for modifications. The description implies batch creation but lacks context on prerequisites, limitations, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_batch_readC
Read multiple tasks in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it's a read operation. It doesn't disclose behavioral traits like rate limits, authentication requirements, pagination, error handling for partial failures, or what happens with invalid IDs. This leaves significant gaps 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 a single, clear sentence with zero wasted words. It's appropriately sized for a simple tool description and front-loads the 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?
For a batch read tool with 1 parameter (but complex nested structure), 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain the input structure, output format, error behavior, or performance characteristics needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but adds nothing about parameters. It doesn't explain what 'inputs' contains, the purpose of 'id', 'properties', or 'associations', or how to structure the array. This leaves all parameter semantics undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read multiple tasks') and scope ('in a single request'), which distinguishes it from single-task read operations. However, it doesn't explicitly differentiate from other batch read tools for different resources (like calls_batch_read or notes_batch_read), keeping it at a 4 rather than a 5.
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 like tasks_get (for single tasks) or tasks_list (for listing with filters). There's no mention of performance trade-offs, prerequisites, or error handling for batch operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_batch_updateC
Update multiple tasks in a single request
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. While 'Update' implies mutation, the description doesn't disclose important behavioral traits like whether this requires specific permissions, if updates are atomic or partial, what happens on partial failures, or rate limiting considerations. For a batch mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the core functionality, though this conciseness comes at the cost of completeness.
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 mutation tool with complex nested parameters (1 parameter with deep nesting), 0% schema description coverage, no annotations, and no output schema, the description is severely incomplete. It doesn't address error handling, response format, permissions, or provide any context about the task properties that can be updated.
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 0% schema description coverage and a complex nested parameter structure (array of objects with id and properties), the description adds no parameter information beyond the tool name. It doesn't explain what 'inputs' should contain, the required fields, or the meaning of the various hs_task_* properties 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 action ('Update multiple tasks') and the scope ('in a single request'), which provides a specific verb+resource combination. However, it doesn't explicitly distinguish this batch operation from the individual 'tasks_update' sibling tool, which would be helpful for 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 no guidance on when to use this batch update tool versus the individual 'tasks_update' tool, nor does it mention prerequisites, error handling, or rate limits. Without any usage context, the agent must infer when batch operations are appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_createD
Create a new task
| Name | Required | Description | Default |
|---|---|---|---|
| properties | Yes | ||
| associations | No |
TDQS
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. 'Create a new task' implies a write/mutation operation but provides no information about permissions required, whether the operation is idempotent, what happens on failure, rate limits, or what the response looks like. For a mutation tool with zero annotation coverage, this is completely inadequate.
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 at just three words. While this represents severe under-specification rather than effective conciseness, from a pure length perspective it's minimal and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with complex nested parameters, no annotations, and no output schema. The description provides only the barest minimum information ('Create a new task') without explaining what parameters are needed, what the operation does, when to use it, or what to expect in return. For a tool of this complexity, the description is completely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions no parameters whatsoever, despite the input schema having 2 top-level parameters (properties and associations) with complex nested structures and 8 specific task properties. With 0% schema description coverage, the description fails completely to compensate by explaining what parameters are needed or their purpose.
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 'Create a new task' is a tautology that essentially restates the tool name 'tasks_create'. It doesn't provide any additional specificity about what kind of task is being created, what system it's created in, or how it differs from other task-related tools like 'tasks_batch_create' or 'tasks_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 absolutely no guidance about when to use this tool versus alternatives. There are multiple sibling tools for tasks (tasks_batch_create, tasks_update, tasks_archive, etc.), but the description offers no context about when this single-create operation is appropriate versus batch operations or other task management functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_getC
Get details of a specific task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| properties | No | ||
| associations | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Get' which implies a read operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, error handling, or what happens with invalid task IDs. The description is too minimal to provide adequate behavioral context for a tool with parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence with zero wasted words. The description is front-loaded with the core purpose. While under-specified, it's efficiently structured without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain what details are returned, how parameters work, or behavioral aspects. The minimal description fails to provide sufficient context for proper tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'specific task' which hints at the taskId parameter, but doesn't explain the 'properties' or 'associations' parameters at all. The description adds minimal value beyond what's implied by the tool name, leaving most parameters undocumented.
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 'Get details of a specific task' clearly states the verb ('Get') and resource ('task'), but it's vague about what 'details' includes and doesn't distinguish from sibling tools like tasks_list or tasks_search. It provides basic purpose but lacks specificity about scope or 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?
No guidance on when to use this tool versus alternatives like tasks_list or tasks_search. The description implies it's for retrieving details of a single task, but doesn't specify prerequisites, error conditions, or comparison with sibling tools. Minimal implied usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_listC
List all tasks with optional filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| after | No | ||
| properties | No | ||
| associations | No | ||
| archived | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states 'List all tasks with optional filtering', which doesn't reveal any behavioral traits such as pagination behavior (implied by 'limit' and 'after' parameters but not described), rate limits, authentication needs, whether it's read-only (implied but not explicit), or what happens with archived tasks (related to 'archived' parameter). This leaves significant gaps for an agent to understand how the tool behaves beyond basic listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence: 'List all tasks with optional filtering'. It's front-loaded with the core action and resource, with no wasted words. However, it's overly brief given the complexity of 5 undocumented parameters, which could benefit from slightly more detail without sacrificing efficiency.
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 (5 parameters, 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't address key aspects like parameter meanings, behavioral traits (e.g., pagination, handling of archived tasks), or how it differs from sibling tools. For a list tool with multiple filtering options, more context is needed to guide effective use by 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 description mentions 'optional filtering' but doesn't specify what parameters are available or their meanings. With 5 parameters and 0% schema description coverage, the schema provides no descriptions for any parameters. The description fails to compensate by explaining parameters like 'limit', 'after', 'properties', 'associations', or 'archived', leaving their semantics unclear beyond what can be inferred from names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all tasks with optional filtering' clearly states the verb ('List') and resource ('tasks'), making the basic purpose understandable. However, it lacks specificity about what kind of tasks (e.g., CRM tasks, project tasks) and doesn't differentiate from sibling tools like 'tasks_search' or 'tasks_get' beyond the mention of 'optional filtering' which is vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like 'tasks_search' or 'tasks_get'. The phrase 'optional filtering' hints at some usage context but doesn't clarify what filtering options exist or when to choose this over other list/search tools. There's no mention of prerequisites, exclusions, or specific scenarios for application.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_searchD
Search tasks with specific filters
| Name | Required | Description | Default |
|---|---|---|---|
| filterGroups | Yes | ||
| properties | No | ||
| limit | No | ||
| after | No | ||
| sorts | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. 'Search tasks with specific filters' doesn't reveal whether this is read-only, paginated, rate-limited, requires authentication, or what the return format looks like. It's completely inadequate for a search tool with complex filtering capabilities.
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 (4 words), but this brevity comes at the cost of being under-specified rather than efficient. While front-loaded, it doesn't provide enough information to be genuinely helpful. It's not verbose, but it's also not adequately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex search tool with 5 parameters (including nested filtering logic), no annotations, no output schema, and 0% schema description coverage. The description is completely inadequate for this context - it doesn't explain the filtering system, pagination, sorting, or what properties can be searched. The agent would struggle 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?
Schema description coverage is 0%, meaning none of the 5 parameters are documented in the schema. The description mentions 'specific filters' which hints at the 'filterGroups' parameter but doesn't explain any of the other parameters (properties, limit, after, sorts) or provide syntax/format guidance. It fails to compensate for the complete lack of schema 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 'Search tasks with specific filters' states the basic action (search) and resource (tasks), but it's vague about what 'specific filters' means and doesn't distinguish this tool from sibling tools like 'tasks_list' or 'tasks_get'. It restates the name/title concept without adding meaningful 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 no guidance on when to use this tool versus alternatives like 'tasks_list' or 'tasks_get'. There's no mention of prerequisites, appropriate contexts, or exclusions. The agent must guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tasks_updateC
Update an existing task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| properties | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update an existing task' implies a mutation operation, but it doesn't disclose behavioral traits such as required permissions, whether updates are partial or full, error handling, or what happens if the task doesn't exist. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence, 'Update an existing task', which is front-loaded and wastes no words. While it may be under-specified, it earns a high score for conciseness as every word serves a clear purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (mutation tool with nested objects, no output schema, and no annotations), the description is incomplete. It doesn't cover parameter meanings, usage context, behavioral details, or return values. For a tool that modifies data with multiple fields, this minimal description fails to provide adequate context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about parameters. With schema description coverage at 0% and 2 parameters (taskId and properties), the schema documents the structure but not the meaning. The description doesn't compensate by explaining what 'taskId' refers to or what 'properties' contains (e.g., task fields like body, priority). This leaves key semantics undocumented.
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 'Update an existing task' clearly states the verb (update) and resource (task), but it's vague about what specifically gets updated. It doesn't distinguish this tool from sibling tools like 'tasks_batch_update' or 'tasks_update' (if there were multiple task update tools), though the sibling list shows only one 'tasks_update' tool. The purpose is understandable but lacks specificity about scope or fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes 'tasks_batch_update' for batch operations and 'tasks_create' for creating new tasks, but the description doesn't mention these alternatives or specify prerequisites like needing an existing task ID. Usage is implied only by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Tools are well-organized by resource types (calls, communications, CRM objects, etc.) with clear action distinctions (create, get, update, archive, search, list). However, some overlap exists between 'list' and 'search' tools across resources, which could cause minor confusion about when to use each, though descriptions help clarify.
Naming follows a highly consistent pattern throughout: resource_action (e.g., calls_create, crm_get_company) with batch operations as resource_batch_action. This verb_noun structure is uniform across all 112 tools, making them predictable and easy to understand.
With 112 tools, the count is excessive for a single server, leading to potential overwhelm and inefficiency. While it covers many HubSpot resources, the sheer volume suggests poor scoping, as many tools could be consolidated or parameterized (e.g., using generic object types instead of separate tools for each resource).
The tool set provides comprehensive CRUD and lifecycle coverage across multiple HubSpot domains (calls, communications, CRM, emails, engagements, meetings, notes, products, tasks). Each resource type includes create, read, update, delete (archive), list, search, and batch operations, leaving no obvious gaps for agent workflows.
Related MCP Connectors
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
Create, search, update, and manage data in OnePageCRM.
MCP server for the HubSpot Integrations Center HubDB: search and retrieve integration data.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/Koozow/hubspot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server