GoHighLevel MCP Server

Server Quality Checklist

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

Latest release: v0.2.0
Disambiguation4/5
Tool names consistently include the target resource (contact, opportunity, invoice, task, note, etc.), so most actions are clearly distinct even with 114 tools. A few near-neighbor pairs—custom_field vs custom_value, contact_note vs appointment_note, and association vs relation—could require careful description reading, but they are not genuinely interchangeable.
Naming Consistency4/5
The dominant ghl_<verb>_<noun> pattern is clear and mostly followed. However, several plural list operations use get_ instead of list_ (ghl_get_calendars, ghl_get_pipelines, ghl_get_messages, ghl_get_form_submissions), and ghl_estimate_to_invoice breaks the verb_noun pattern.
Tool Count1/5
114 tools is an extreme count for an agent-facing MCP server; even though GoHighLevel covers many domains, this surface is far beyond the 3-15 tool range considered well-scoped. The sheer number will overwhelm tool selection and context windows regardless of how individually useful the tools are.
Completeness3/5
The server covers a very wide range of GHL resources with strong CRUD coverage for contacts, tasks, notes, products, tags, custom values, and businesses. Notable gaps exist, though: there is no ghl_get_estimate (making estimate updates awkward), no ghl_update_invoice, and no delete for opportunities, leaving some lifecycle dead ends.
Average 3.7/5 across 114 of 114 tools scored. Lowest: 2.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Destructive,' which merely repeats the destructiveHint annotation. It adds no additional behavioral context such as whether deletion is permanent, affects related entities, or requires special permissions. With annotations already carrying the safety profile, the description adds nothing beyond what structured data provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, but both are redundant: 'Delete a custom value' restates the title, and 'Destructive' restates the annotation. It achieves brevity at the cost of essential information, making it under-specified rather than genuinely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description should explain consequences (e.g., irreversibility, cascading effects) and what a custom value is. It provides none of this, leaving the agent without enough context to confidently invoke the tool or interpret results. The sibling list contains many similarly named delete tools, increasing the need for differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes locationId but leaves customValueId without a description (50% coverage). The description does not explain the purpose or format of either parameter, nor does it compensate for the missing customValueId documentation. For a required parameter, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Delete a custom value.' This is specific and not a pure tautology, though it closely mirrors the title. It doesn't explicitly differentiate from sibling delete operations like ghl_delete_custom_field, but the resource name is distinct enough for an agent to identify the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as ghl_update_custom_value or ghl_delete_custom_field. There is no mention of prerequisites, use cases, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description merely repeats 'Destructive,' which is already captured by the destructiveHint annotation. It adds no new context such as irreversibility, impact on links or references to the media file, or any side effects. The openWorldHint and idempotentHint are not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action, but the second sentence 'Destructive.' is redundant with the annotations and adds no value. It is concise but not efficiently informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, an agent needs to know consequences (e.g., permanent deletion, impact on URLs) and any required context. The description provides none of that, leaving the agent to rely solely on annotations for safety awareness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (fileId lacks a description). The description does not mention either parameter or clarify what fileId refers to, so it fails to compensate for the missing schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (delete) and resource (file from Media Library), which distinguishes it from other delete tools like delete_contact or delete_invoice. It could be more explicit about the scope (e.g., permanent deletion), but it is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites (e.g., needing the fileId), or contrast with similar media operations like upload_media_by_url or list_media.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Destructive.' which merely restates the destructiveHint: true annotation. It adds no additional behavioral context such as irreversibility, side effects, authorization requirements, or response behavior. With annotations present, the description fails to add value beyond what annotations already declare.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded ('Delete a custom object record.'). It is efficient with no wasted words, though the succeeding sentence 'Destructive.' is redundant given the annotation. Still, conciseness is a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with three parameters and no output schema, the description is insufficient. It does not mention what happens after deletion (return value), idempotency behavior (though annotation hints idempotent), or any operational details. Agents cannot fully anticipate the tool's behavior from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId has a description). The tool description does not clarify the role of recordId or schemaKey, and does not compensate for the missing schema documentation. Agents receive no explanation of these required parameters from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (Delete) and resource (custom object record), which is clear enough to distinguish from other resource-specific delete tools. However, it relies on the tool name and title for precision, and does not explicitly differentiate from sibling delete tools (e.g., ghl_delete_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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, or conditions that favor this tool over similar delete operations. The description provides no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and openWorldHint=true. The description's 'Fetch' is consistent but adds no extra behavioral context beyond what annotations already provide. It does not disclose error behavior, auth requirements, or response format, so it offers minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is concise and front-loaded. However, it is so brief that it under-specifies required context, skipping parameter semantics and usage. It earns a high mark for brevity but not for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, low parameter coverage, and no usage guidance, the description is inadequate for a tool that requires correct subscription identification. An agent would lack clarity on what to supply and what to expect in return, other than the basic fetch action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (locationId is described, subscriptionId is not). The description does not elaborate on any parameter, failing to compensate for the gap. With no parameter detail, an agent may not know that subscriptionId is the primary identifier and locationId is optional with a default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches a single subscription by id, with a specific verb and resource. It doesn't explicitly distinguish from the sibling ghl_list_subscriptions, but 'by id' implies it targets one record, so the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as ghl_list_subscriptions. There is no context about required prerequisites (e.g., location context) 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true and openWorldHint=true, and the description does not contradict them. However, the description adds no behavioral context beyond those annotations: it does not mention pagination behavior via skip/limit, the need for schemaKey, the nature of the text query, or what response shape to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no wasted words, which is concise. However, it is under-specified for a tool with five parameters and important behavioral details; the brevity comes at the cost of usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description must carry more explanatory weight, but it does not. It lacks mention of required schemaKey, pagination semantics, query matching behavior, or how this search differs from other search/list tools, leaving the agent under-informed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, with query and locationId documented in the schema but skip, limit, and schemaKey left undocumented. The description adds minimal value by saying 'text query,' which overlaps with the schema's already-present 'Free-text search' description. It does not explain the required schemaKey parameter or the pagination parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search'), a clear resource ('records of a custom object'), and the mechanism ('by a text query'). It is understandable on its own and distinguishable from direct-fetch siblings like ghl_get_object_record, though it does not explicitly name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as ghl_get_object_record, ghl_list_object_schemas, or ghl_search_contacts. The description implies it is for text-based search but does not state exclusions, prerequisites, or when direct retrieval is more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false), potential side effects (openWorldHint=true), and non-idempotency (idempotentHint=false). The description adds no behavioral details beyond this, such as what happens if a tag with the same name already exists, or any side effects of creation. It merely restates the action without enlightening the agent on consequences or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core action. It contains no redundant words and clearly states the purpose. It is appropriately sized for a simple create operation, scoring high on conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should convey return values, but it does not. It also does not mention potential use cases, errors, or uniqueness constraints. While the tool is simple, the description leaves out critical operational details like whether the created tag's ID is returned, making it insufficient for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only locationId has a description). The tool description does not add any clarification for the 'name' parameter, which has no schema-level description. It does not explain what format the name should take, whether it must be unique, or any validation. The description provides no value beyond the schema, failing to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (create), resource (tag), and scope (location's master tag list). It is unambiguous about the tool's function, though it does not explicitly differentiate from sibling tools like ghl_update_tag or ghl_delete_tag. The purpose is clear enough for an agent to understand the core action, but lacks explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of when to create a new tag, what prerequisites exist, or when to use ghl_update_tag or ghl_delete_tag instead. This leaves the agent without contextual direction on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no additional behavioral context such as return format, error cases, or what constitutes a 'custom value'. It simply restates the operation without adding insight beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately terse for a simple get operation, though this economy comes at the cost of missing essential details captured in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and the sparse description, an agent is left without knowledge of the return structure or how this tool differs from closely related ones like ghl_get_custom_field. The description does not cover error handling, presence of results, or any operational nuances, making it incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only 50% of parameters (locationId has a description, customValueId does not). The description's 'by id' redundantly refers to customValueId but does not clarify its format or meaning. It fails to compensate for the missing schema documentation, leaving the agent to infer the id's nature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a single custom value by id.' is specific with a clear verb (fetch), resource (custom value), and method (by id). The word 'single' distinguishes it from list operations, though it does not explicitly name a sibling alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like ghl_list_custom_values or ghl_get_custom_field. The description implies a get-by-id scenario but does not state exclusions or provide routing to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds no behavioral context beyond that — no pagination behavior, no mention of what happens for an invalid funnel, no return shape. It does not contradict the annotations, but it also contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single eight-word sentence with no fluff or repetition; it is both appropriately sized and front-loaded. It is borderline under-specified, which caps the score slightly below a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool this is workable, but the description is essentially the title restated. It omits how to obtain the required funnelId, how pagination behaves, and what the response contains — and with no output schema, those gaps are not covered elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 40%, the description should compensate for the undocumented parameters, but it says nothing about funnelId, name, limit, or offset. The schema's defaults and bounds partly self-document limit/offset pagination, and funnelId's role is inferable from the tool name, so the gap is not catastrophic — but the description adds zero parametric meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('pages within a funnel'), making the operation unambiguous. It naturally differentiates from the closest sibling ghl_list_funnels, which targets funnels as top-level entities, though it never explicitly names that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention that the funnel must exist first, and no hint that funnelId is likely obtained from ghl_list_funnels. The use case is only implied by the tool's name and title, not explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutating (readOnlyHint=false), idempotent, and open-world behavior, but the description adds no behavioral detail beyond 'update'. It does not disclose whether properties are merged or fully replaced, what happens if the record does not exist, or whether unspecified properties are preserved. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler words. It is concise, though slightly under-sized given the tool's four parameters and nested properties object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three required parameters, a nested properties object, and no output schema, the description is far too minimal to support correct invocation. It omits how to obtain schemaKey, the expected shape of properties, update semantics, and any return or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with only locationId described, so the description was responsible for clarifying the other parameters. It only repeats 'properties' and does not explain that schemaKey identifies the custom object schema, recordId identifies the target record, or that properties is a map of field values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('update'), resource ('custom object record'), and scope ('properties'), which distinguishes it from get/create/delete record tools. It is clear but does not explicitly differentiate it from sibling update tools or describe how it relates to ghl_search_object_records or ghl_get_object_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus ghl_create_object_record or ghl_delete_object_record, and no mention of prerequisites like needing an existing schemaKey or recordId. Usage can only be implied from the verb 'update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal it's a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds only the bare fact of renaming, with no mention of side effects (e.g., name update everywhere), reversibility, permissions, or failure modes. It doesn't contradict annotations but adds minimal behavioral context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words, front-loaded with the core action. It is appropriately concise for a simple operation, though it borders on under-specification. Structure is clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and low schema coverage, the description is incomplete. It lacks parameter semantics, usage guidance, and return value information. The annotations provide safety hints, but the description alone is insufficient for an agent to call it correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId has a description). The description doesn't explain tagId or name, though the names are self-explanatory. It would need to clarify that 'name' is the new name and tagId identifies the tag, which is missing. With low coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Rename an existing tag' with a specific verb and resource. It distinguishes from create/delete tag siblings, though it doesn't explicitly name them. The purpose is unambiguous and precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., ghl_create_tag, ghl_delete_tag). It doesn't mention prerequisites like the tag needing to exist, or when to prefer it over other update operations. Usage context is entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a write operation (readOnlyHint=false, idempotentHint=false). The description adds no behavioral context beyond the basic act of creating, such as side effects, ownership semantics, uniqueness requirements, or required location context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with the action and resource front-loaded and no filler. It loses a point because it largely restates the title 'Create business,' contributing little new informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 10 parameters, one required, no output schema, and low schema documentation, a one-sentence description is inadequate. Missing details include required field semantics, default locationId behavior, address field expectations, and what the created record looks like in response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10% (only locationId has a description), yet the description mentions none of the 10 parameters. It does not clarify what 'name' must be, how address fields relate, or how locationId defaults work. The description must compensate for poor schema coverage but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create a business (company) record.' This clearly distinguishes the tool from siblings like ghl_create_contact, ghl_create_opportunity, and ghl_create_appointment. No ambiguity remains about what entity this tool creates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool instead of related tools such as ghl_update_business, ghl_get_business, or other create tools. There are no preconditions, exclusions, or alternative routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint false) and non-idempotent, so the description need not repeat that. However, it adds no information about behavior beyond creation — e.g., whether duplicate names are rejected, whether the operation is scoped to a location by default, or what happens on failure. The openWorldHint true isn't elaborated. The description carries no extra behavioral context beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with the action and key parameters front-loaded. It avoids extraneous wording and is easy to parse. However, it might be slightly too terse, missing nuance about the locationId parameter and the merge field concept.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no mention of return values, success indicators, or error conditions, an agent cannot fully anticipate the call's outcome. The description misses the locationId default (though the schema covers it) and does not clarify whether the operation is scoped to a specific location or the default. Given it's a mutation with openWorldHint true, more context about side effects or uniqueness would be valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId has a schema description). The description names 'name' and 'value' as required but does not explain what constitutes a valid name or value (e.g., allowed characters, length limits, uniqueness constraints). Since coverage is low, the description should compensate, but it offers no additional semantics beyond restating the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create' and the resource 'custom value (merge field)', which is specific enough to distinguish from the many related CRUD tools like update/delete/list. The parenthetical clarifies what a custom value is, adding a useful hint. However, it doesn't explicitly contrast with the separate 'custom field' tool (ghl_create_custom_field), so a slight ambiguity remains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (create a new custom value when needed), but it does not explicitly state when to use this over alternatives (e.g., when to use update vs create, or whether this is for a specific location). Given the sibling list includes update/delete/list, an explicit note about 'use this to create a new value, use update to modify an existing one' would improve it. No such guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Destructive,' but this only restates the existing destructiveHint=true annotation and adds no new behavioral context—no mention of permanence, cascading effects on related records, permissions, or constraints on deleting converted estimates. With annotations carrying the safety profile, the description contributes no incremental transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with the action, containing no padding. One minor deduction because 'Destructive' is redundant with the destructiveHint annotation, so not every word adds incremental value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, the description leaves important domain context unstated—such as whether an estimate can be deleted after being sent or converted to an invoice. The schema and annotations provide required parameters and safety flags, but the description alone does not give an agent enough caveats to avoid misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 50% of parameters have schema descriptions; estimateId has no description, and locationId is documented in the schema. The tool description mentions neither parameter, so it adds no meaning beyond the schema for identifying which estimate to delete or how the default location behaves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource, 'Delete an estimate,' which unambiguously identifies the operation and distinguishes it from the many delete-* siblings by naming the resource. The appended 'Destructive' reinforces the nature of the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose this tool over alternatives such as ghl_update_estimate, ghl_send_estimate, or ghl_estimate_to_invoice. The description merely states the action, leaving the agent to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description only adds 'Destructive.' which merely repeats the destructiveHint annotation, adding no new behavioral context. It does not mention return values, side effects, or any special behaviors not already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded with the action. However, 'Destructive.' is redundant with the destructiveHint annotation, so it does not earn its place. The message is concise but includes a superfluous word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no output schema, the description is under-specified. It does not mention what the tool returns, whether deletion is permanent or reversible, or any downstream effects on related data. Annotations mitigate the 'destructive' awareness, but the description alone leaves an agent without enough information to fully anticipate the operation's outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: locationId has a description, but productId does not. The tool description adds no parameter information, so an agent gains no extra understanding of productId's purpose or format beyond the schema's minimal type field. The description does not compensate for the incomplete schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a product.' This clearly differentiates it from siblings like ghl_get_product, ghl_create_product, and ghl_update_product. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, consequences (e.g., cascading deletions), or a scenario where another operation (like updating status) might be preferred. The description offers no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description's 'Destructive' adds no new behavioral information beyond the structured data. It does not explain whether only the relation link is removed, whether the operation is reversible, or what happens if the relationId does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, with the core action stated immediately. The standalone 'Destructive' sentence is a fragment that mostly duplicates the annotation, mildly reducing the efficiency, but overall it remains appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core operation is stated and the annotations cover safety and idempotency, so an agent can understand the basic call. However, the description omits useful context such as what a GHL relation is, how to discover relationId, and whether the linked records themselves remain untouched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the required relationId parameter has no schema description. The tool description does not compensate by explaining relationId's format, provenance, or how it maps to the two records, leaving a meaningful gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete') and resource ('relation'), and clarifies the scope as 'between two records.' This clearly distinguishes it from sibling relation tools like ghl_create_relation and ghl_get_record_relations, as well as from delete tools targeting other GHL resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are prerequisites such as obtaining a relationId via ghl_get_record_relations mentioned. The word 'Destructive' is a warning, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds the note/contact relationship but does not disclose response shape, error behavior, or what happens if the note is not found. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loads the action and resource, and every word earns its place. It is appropriately sized for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, the description is mostly sufficient, but it leaves the roles of the two IDs implicit and does not mention return or error behavior. Since there is no output schema, a bit more context about what the tool returns would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should clarify how contactId and noteId are used. It only says 'by id,' which is ambiguous with two required IDs. The parameter names are self-explanatory, but the description does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Fetch a single note on a contact by id.' This clearly separates the tool from note list/create/update/delete siblings. The only minor weakness is that 'by id' is ambiguous because the schema has both contactId and noteId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives such as ghl_list_contact_notes. The phrase 'a single note' implies it is for retrieving one specific note, but no when-to-use or when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds no further behavior (e.g., error handling, return format, or required configuration). The description is consistent with the annotations but adds only the trivial notion of fetching by ID, which is already implied by the name. This meets the baseline for annotation-covered safety but adds little beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. It is appropriately front-loaded with the essential verb and object, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool requires schemaKey and recordId, yet the description does not explain what schemaKey is or how to obtain it, nor does it describe the return value (no output schema). There is no mention of error behavior or prerequisites beyond the implicit ID. For a simple getter, this is a notable gap that could mislead an agent into calling it incorrectly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only locationId has a description). The description itself says 'by id' but does not clarify which parameter is the id, nor does it explain the required schemaKey parameter or its meaning. With low schema coverage, the description should compensate but does not, leaving agents under-informed about the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('single custom object record') with a clear scope ('by id'). It distinguishes itself from siblings like ghl_search_object_records (search) and ghl_get_object_schema (schema), making it immediately clear what this tool does versus alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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, no prerequisites (e.g., needing a schemaKey or locationId), and no mention of when not to use it. There is zero routing or context-setting information beyond the bare action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The word 'Destructive' restates the destructiveHint annotation and adds no new behavioral context, such as whether deletion cascades to related records, is reversible, or requires special permissions. The annotations already carry the safety profile, but the description contributes nothing beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core action is front-loaded, and the destructive warning is immediate. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation with annotations covering destructiveness, the description is minimally viable. However, it does not mention what happens after deletion, whether the operation is reversible, or what response to expect, and there is no output schema to fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description needed to compensate by explaining the businessId parameter, but it does not mention it at all. The parameter name suggests a business identifier, and the description confirms the target is a business record, but no format, source, or additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Delete') and resource ('a business record'), which distinguishes it from sibling tools like ghl_delete_relation and ghl_update_business. It is direct and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as ghl_update_business or ghl_delete_relation. It does not mention prerequisites, exclusions, or conditions under which a different tool should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so there is no safety contradiction. The description adds no behavioral context beyond that read-only fetch, such as not-found behavior, authentication scope, or whether linked data is included. It is a minimal statement of the operation rather than a disclosure of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence that names the action, object, and key. Every word earns its place; there is no filler or redundant content. It is appropriately sized for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with readOnly/openWorld annotations, the description is nearly sufficient but leaves gaps: no explicit statement of what a caller receives, no error/not-found expectations, and no differentiation guidance among appointment-related siblings. It is adequate for a trivial get-by-id but not richly contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (appointmentId) with 0% description coverage, and the tool description only says 'by id.' It does not explain the format, source, or semantics of the id beyond what the parameter name already conveys. The description therefore adds little parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a precise resource ('a single calendar appointment/event'), and a selection mechanism ('by id'). The word 'single' distinguishes it from plural/list sibling tools like ghl_get_calendar_events, so an agent can identify this as the point lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, prerequisites, or alternative conditions. It does not tell the agent to prefer this tool over ghl_get_calendar_events or ghl_get_free_slots, nor when not to use it. This is implied at best by 'by id'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false (mutation) and idempotentHint=true. The description adds the behavioral detail that removal halts the workflow for the contact, which is useful context beyond the annotations. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. It front-loads the action and effect, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 required parameters, no output schema, and 0% schema description coverage, the description fails to explain the parameters or any edge cases. It is minimal and leaves the agent to guess parameter semantics, making it incomplete despite the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 does not explain what contactId and workflowId represent beyond the parameter names. The description only states the action, leaving parameter semantics to be inferred from the names, which is insufficient given zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove') and resource ('contact from an automation workflow'), and adds the effect ('halting it for them'). It is clearly distinct from sibling tools like ghl_add_contact_to_workflow by the opposite action, though it does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use when you want to halt a contact's workflow. However, it gives no explicit guidance on when not to use it, prerequisites, or alternatives. It does not mention the companion add tool or any conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write (readOnlyHint=false) and idempotent (idempotentHint=true). The description is consistent with these and adds no contradictory behavior. However, it doesn't clarify whether the update is a full replacement or partial, nor mention any side effects or permission requirements. Given annotations cover some traits, the description adds minimal additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is appropriately concise and front-loaded with the primary action. It could arguably be expanded with usage details, but for what it includes, it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low schema coverage, lack of output schema, and no usage guidelines, the description is incomplete for a mutation tool. It does not mention error scenarios, behavior for nonexistent notes, or how userId affects the operation. Siblings like ghl_update_contact_note exist, so differentiation guidance would be valuable but is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only 'body' has a description). The tool description adds no explanation for contactId, noteId, or userId, which are not described in the schema either. The description does not compensate for the low schema coverage, leaving parameter meaning mostly inferred from names rather than explicit documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update the text') and the resource ('an existing note on a contact'), distinguishing it from siblings like create, delete, and get contact note. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like ghl_create_contact_note or ghl_delete_contact_note. No context about prerequisites, such as needing an existing note or the significance of the optional userId. The description simply states the operation without usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent operation (readOnlyHint false, idempotentHint false), and the description does not contradict that. It adds the useful validation hint that properties must match the schema's property keys, but does not disclose failure behavior or response contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The main action is stated first and the critical properties constraint is second, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple create call but lacks important context: what schemaKey refers to, how to discover valid schemas, and what the tool returns. With no output schema, some mention of return value would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is about 67%, so the description needs to add some meaning. It clarifies that 'properties' is a key/value map aligned with the schema's property keys, which is helpful, but it leaves 'schemaKey' undefined in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a create action on 'a record for a custom object', which is a specific verb and resource. It does not explicitly distinguish itself from sibling operations like ghl_update_object_record or ghl_get_object_record, relying on the verb and title instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over alternatives, nor are prerequisites mentioned. An agent is not told to look up the schema first via ghl_list_object_schemas or ghl_get_object_schema, nor that updates should go to ghl_update_object_record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Destructive,' which only repeats the destructiveHint=true annotation already present. It does not add behavioral detail beyond the annotations, such as whether deletion is permanent, cascades to related data, or requires special permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded with the core action. The 'Destructive' sentence is redundant with the annotation, so it does not fully earn its place, but the overall structure is compact and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter destructive operation with annotations covering the safety profile, the description is minimally viable. However, it lacks context about the permanent effect, whether the trigger link must exist, or what the response looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain linkId beyond what the schema already shows. The parameter name is somewhat self-explanatory, but the description adds no meaning about how to obtain or format the link ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Delete') and resource ('trigger link'). The tool name and sibling tools make its role distinct from ghl_create_trigger_link and ghl_list_trigger_links, so an agent can easily understand what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the delete verb and the required linkId parameter, but there is no explicit guidance about when to choose this tool over alternatives, prerequisites, or exclusions. No when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and openWorldHint, so the description's job is to add non-obvious behavioral context. 'Participates in' hints that relations may be bidirectional, which is mildly useful, but it does not disclose pagination behavior, scoping nuances, or response characteristics beyond what schema and annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with the verb and object front-loaded and no filler or repetition. It is appropriately concise for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and schema, the description covers the basic action but lacks disambiguation from a similarly named sibling and gives no sense of what a returned relation looks like. For a tool with no output schema and an openWorldHint, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, yet the description mentions none of the parameters. It does not compensate for the low coverage by explaining recordId, skip/limit pagination, or the locationId default, leaving the agent to infer meaning solely from names and schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'List' as a specific verb and names 'relations' as the resource, scoped to 'a given record,' so an agent can understand this is a read operation. However, it does not explicitly distinguish itself from the sibling ghl_list_associations, whose name suggests a similar responsibility, so it misses a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: call it when you need the relations a particular record participates in. It provides no explicit when-to-use or when-not-to-use guidance, and the sibling list contains ghl_create_relation, ghl_delete_relation, and ghl_list_associations that could be confused with this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the partial-update behavior ('Only provided fields change'), which is valuable context beyond the annotations' readOnlyHint=false and idempotentHint=true. However, it does not describe other behavioral aspects like required permissions, side effects, or the return value. Given the annotations already indicate mutation, the description adds some context but not enough to be more than adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action, followed by concrete examples and a key behavior note ('Only provided fields change'). There is no wasted wording, making it appropriately concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters and no output schema, so the description should provide guidance on expected input formats (e.g., date format, assignee identifiers) and mention the response behavior. It covers neither, leaving agents to guess critical details. The example hints are insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 all parameters. It provides examples for dueDate, assignedTo, and completed, but does not cover title or body. It offers partial meaning through examples, but a 7-parameter tool with 0% coverage needs more explicit parameter explanations to avoid ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a clear verb (update) and resource (contact task), provides concrete examples of what can be changed (completed, due date, assignee), and distinguishes it from sibling tools like create/delete/get task. It is not a tautology and conveys the core function effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like ghl_create_contact_task or ghl_get_contact_task. The description implies it is for modifying existing tasks, but it does not state when-not-to-use it or mention any competitors. Usage is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the mutation and idempotency profile (readOnlyHint=false, idempotentHint=true), so the description's job is lighter. It adds the useful nuance that name and/or value can be changed, but it doesn't disclose side effects, permissions, or whether unchanged fields must still be supplied despite the 'and/or' wording.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler or repetition. It earns its place by stating the verb, resource, and mutable fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the schema plus annotations carry a fair amount of context, so the minimal description is usable. Still, there is no explanation of what a custom value is, no mention of return behavior (no output schema), and no pointer to ghl_list_custom_values to obtain customValueId, leaving the agent to infer context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage, the description partially compensates by clarifying that name and value are the updatable fields and that customValueId identifies the target. It adds little beyond the parameter names, though, and does not explain the meaning of a custom value or the behavior of the required fields in a partial update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Update') and resource ('custom value') and identifies the mutable fields (name and/or value), making it distinct from create/get/delete siblings. However, it doesn't explicitly differentiate from related update tools like ghl_update_custom_field, relying on the resource type to carry that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no when-to-use guidance, prerequisites, or references to alternatives such as ghl_create_custom_value or ghl_list_custom_values. The operation is implied by the verb, but the description does not help the agent reason about when this tool is appropriate versus other update/list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint=true and openWorldHint=true, so the safety profile is established. The description adds mild context (single-item retrieval scoped to a contact) but discloses nothing beyond that; this is acceptable for a simple read operation with annotations present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single nine-word sentence that is front-loaded with the verb and contains zero filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with readOnlyHint/openWorldHint annotations, the description is largely sufficient. Minor gaps remain: there is no output schema, so the return shape is undocumented, and error behavior (e.g., task not found) is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. 'by id' maps to taskId and 'on a contact' maps to contactId implicitly, giving partial semantic meaning, but the mapping is not explicit and neither parameter's format or purpose is spelled out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a resource ('a single task on a contact'), and a scope ('by id'). This effectively distinguishes it from ghl_list_contact_tasks for the agent, though it does not explicitly name any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to call this tool versus alternatives such as ghl_list_contact_tasks or ghl_get_contact. There are no usage conditions, exclusions, or references to related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint: true` and `openWorldHint: true`, so the read-only nature is covered. The description adds a small behavioral detail by noting the fetch 'including its properties', which clarifies the output scope, but otherwise does not disclose additional behavioral traits such as error handling or availability of the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the action and includes an example key. There is no filler or redundancy; every word contributes to specifying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch with two well-documented parameters and helpful annotations, the description is largely complete. The main minor gap is the absence of guidance on what happens when the key is invalid or not found, and no reference to the related list tool for discovery, but the core call information is adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the schema already documents both `schemaKey` and `locationId` with defaults and examples. The description merely repeats the key format example and adds no new semantic meaning beyond what the parameter descriptions already provide, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch a custom object schema') and the resource ('by key') with a concrete example (`custom_objects.podcast_episode`), making the tool's purpose evident. It distinguishes from the sibling `ghl_list_object_schemas` by emphasizing singular lookup by key, though it does not explicitly name or contrast that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or mention of alternatives such as `ghl_list_object_schemas` for discovering available keys. Usage is only implied by the 'by key' phrasing and the example, which is insufficient for routing an agent between this and the sibling list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the read-only nature, and the description adds little beyond restating 'Fetch'. It does not disclose behavior such as not-found handling, response shape, or any location scoping effects beyond what the schema already provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core meaning and the tool's purpose is immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only get-by-id tool, the schema and annotations cover a fair amount. However, the description is minimal: it lacks explicit alternative routing, error/not-found expectations, and any clarification of the optional locationId scope, leaving the agent to infer some context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description does not compensate for the undocumented productId parameter beyond calling it an 'id'. It also does not explain locationId or its default behavior, which the schema does partially cover, but the description adds no new parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a clear resource ('product'), and a scope ('single ... by id'). This clearly distinguishes it from list_products and other get-style siblings, so an agent can tell what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by id' implies the tool should be used when a specific product ID is known and one product is needed. However, it does not explicitly mention when not to use it or point to ghl_list_products for listing or searching alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds no behavioral transparency beyond what is already structured. It does not mention error behavior, response shape, authorization needs, or what happens when the user does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, repetition, or irrelevant content. It front-loads the core operation and resource immediately, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter, the description is minimally adequate, but it leaves gaps: no mention of alternatives, no parameter details despite 0% schema coverage, and no behavioral context beyond the readOnly annotation. These gaps make it acceptable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the userId parameter beyond the generic phrase 'by id'. While the parameter name is self-explanatory, the description fails to compensate for the lack of schema documentation with any additional detail about format, scope, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and a specific resource ('a single user') with the retrieval criterion ('by id'). It clearly distinguishes this from the sibling ghl_list_users, which would retrieve multiple users, and from other get_* tools targeting different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving one user when the userId is known, but it does not explicitly state when to prefer this over ghl_list_users or any other alternative. There is no exclusionary guidance or explicit when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and potential incompleteness. The description adds little beyond restating the function. It does not disclose pagination, ordering, or response format. The claim of 'all tasks' may conflict with openWorldHint, but not explicitly. No additional behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler. Efficient and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and annotations covering read-only and open-world, the description is minimal but adequate. It does not mention potential pagination or result limits, nor the structure of the returned tasks. Given the openWorldHint, 'all tasks' might be misleading. More detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter contactId with 0% description coverage. The description says 'attached to a contact' but does not explicitly map contactId to the contact identifier. It vaguely implies the relationship but does not explain the parameter's meaning or format. Given the low coverage, the description should clarify, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (tasks), and the scope (attached to a contact). It distinguishes from siblings like ghl_get_contact_task (single task) and ghl_create_contact_task (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of sibling tools like ghl_get_contact_task for retrieving a specific task or ghl_create_contact_task for adding tasks. The description only states the function without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds location scoping and the optional account/date filters as context. However, it does not disclose ordering, pagination behavior, or the implication of openWorldHint (results may drift as posts publish externally), leaving room for more behavioral detail without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. The core purpose leads, and the optional filters follow immediately. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with readOnlyHint=true and no required parameters, the description covers purpose, location scope, and the two key filters. Missing details like pagination and the full type enumeration are modest gaps given the low-risk read context; no output schema exists, so a bit more return-shape guidance would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (43%), so the description carries compensating load. It does address accountIds ('filter by account ids') and date range with ISO 8601 format (fromDate/toDate). However, skip and limit have no schema description and are not mentioned at all, and the full type enum (including draft, in_review, failed) is not conveyed. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List), resource (social posts), and scope (for the location), and clearly distinguishes from siblings like ghl_get_social_post and ghl_list_social_accounts. Slightly imprecise: it says 'scheduled/published' while the type enum also supports all, draft, in_review, and failed — the default is 'all' — so the description understates the full status set, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It never mentions ghl_get_social_post (for retrieving a single post) or ghl_list_social_accounts, and offers no when-not instructions or conditions that would select a sibling. Usage context is only implied by the name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a write operation (readOnlyHint=false), open-world side effects (openWorldHint=true), and non-idempotency (idempotentHint=false). The description adds genuine context beyond this: the matching/deduplication behavior for email/phone and the fact that the created contact is returned. It doesn't disclose potential side effects like workflow triggers, but the annotations cover openness. No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse sentences with no filler: purpose, the key correctness constraint, and the return value. Front-loaded and every sentence earns its place, especially valuable since there is no output schema to document the return.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, 0-required create tool with no output schema, the description covers the core behavioral points (dedup matching, return value) but leaves the undocumented params unsupported and says nothing about side effects beyond what annotations imply. Adequate for the main path, with clear gaps for edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 56%, the description's dedup note adds real meaning for email and phone, which the schema only partially documents (email has no description, phone just a format hint). However, firstName, lastName, and companyName remain undocumented in both the schema and the description, so the description only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new contact,' a specific verb and resource that clearly differentiates this tool from siblings like ghl_get_contact, ghl_update_contact, and ghl_search_contacts. The added dedup context and return-value statement sharpen the purpose. It doesn't explicitly name sibling alternatives, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The dedup recommendation ('At least one of email or phone is recommended so the contact can be matched/deduplicated') gives actionable guidance on how to invoke the tool effectively. However, it never states when to choose create over update/get/search, nor does it mention any exclusions or prerequisites. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=false, indicating a non-idempotent write operation. The description confirms the write action but adds no extra behavioral context, such as that each call creates a distinct note, appends to contact history, or any side effects. openWorldHint=true hints at possible effects, but the description does not elaborate. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single six-word sentence with zero wasted words. The verb is front-loaded and the resource follows immediately. Every word contributes to the meaning, making it an exemplar of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the core action and target contact are clear, and the annotations cover the mutation and non-idempotence aspects. However, the description lacks usage context to distinguish it from other note operations and does not indicate what response to expect, leaving the agent to infer return behavior and preconditions. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes body and userId, while contactId lacks a schema description. The phrase 'to a contact' clarifies that contactId identifies the target contact, adding some meaning beyond the bare parameter name. With 67% schema coverage, the description does not need to compensate heavily, but it also does not elaborate on the body parameter or the userId default behavior already covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('a note to a contact'), making the action unmistakable. It is clearly distinct from sibling operations like ghl_get_contact_note, ghl_update_contact_note, and ghl_delete_contact_note, as well as ghl_create_contact. The title and description align perfectly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention that ghl_list_contact_notes or ghl_get_contact_note are for reading, or that ghl_update_contact_note and ghl_delete_contact_note are for modifying. An agent must infer usage solely from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true, so the read-only nature is covered. The description adds value by stating the payload includes line items and totals, but it doesn't disclose other behavioral aspects such as error handling or pagination. Given annotations cover the safety profile, the description adds some but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. It is efficient with no redundant wording, though it could include a bit more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with 2 parameters and no output schema, the description provides enough to understand the core function and return content (line items/totals). However, it doesn't mention the optional locationId or any prerequisites/error semantics, so it's adequate but not exceptionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% (locationId is described, invoiceId is not). The description says 'by id' which indirectly maps to invoiceId, but it adds no detail about invoiceId format or semantics, and makes no mention of the optional locationId parameter. It only partially compensates for the schema gap, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and resource 'single invoice by id', specifies it includes line items and totals, and implicitly distinguishes it from invoice listing, creation, send, void, and delete siblings. An agent can confidently select this tool when retrieving a specific invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single invoice when an id is known, but it doesn't explicitly state when not to use it or mention alternatives like ghl_list_invoices for broader queries. It provides clear context without exclusions, but lacks explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnlyHint=true and openWorldHint=true annotations, and the word 'Fetch' conveys a read operation. It does not add deeper behavioral context such as error handling, missing-post behavior, or location requirements, but the annotations lower the burden for this simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Every word earns its place and it is appropriately concise for a tool that performs one simple fetch operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool, the schema covers required and optional parameters, and the annotations cover the read-only nature. However, the description does not route the agent away from ghl_list_social_posts, and there is no output schema describing the response shape. The invocation is minimally sufficient but relies on inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The phrase 'by id' adds minimal meaning by clarifying that postId is the lookup key, which is already implied by the schema. Schema coverage is 50%: locationId is described, while postId is not, but the description does not meaningfully compensate for the postId gap. Still, the parameter names and required field are straightforward enough for a basic get-by-id call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Fetch'), a specific resource ('a single social post'), and a selection mechanism ('by id'), which distinguishes it from list/create/delete social post siblings. It does not explicitly name alternatives, but the singular and 'by id' wording makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when a specific postId is known, but it provides no explicit when-to-use or when-not-to-use guidance and does not compare against ghl_list_social_posts or ghl_create_social_post. The intended usage must be inferred from the tool name and required parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true. The description adds partial-update behavior ('Only provided fields are changed') and gives status transition examples, which are not in the schema enum formatting but reflect the valid enum values. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous wording. It delivers the core action and a key behavioral constraint efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with schema and annotations, provides enough for basic invocation: appointmentId is required (from schema), date-time formats are in schema, status enum is in schema, and partial update semantics are in description. However, it omits the updatable title field and fails to mention any response or error handling, leaving some ambiguity for a tool with 5 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%; endTime and startTime have descriptions but title, appointmentId, and appointmentStatus do not. The description refers to 'time' and 'status' but does not clarify that `title` is also updatable, nor does it explain the required `appointmentId` parameter. The 'Only provided fields are changed' hint is helpful but insufficient to fully compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('appointment'), and specifies the scope ('time or status') with examples. It also adds 'Only provided fields are changed' which conveys partial update semantics. However, it omits the 'title' field from the description, which is present in the schema, making the scope slightly under-specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for modifying existing appointments ('Update an appointment's time or status'), and 'Only provided fields are changed' implies a partial update. However, it does not explicitly state when to use this over create/delete alternatives, nor does it provide exclusions or prerequisites such as requiring an existing appointmentId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false). The description adds valuable non-obvious behavior: partial updates ('Only provided fields change'), which is beyond what annotations convey. It does not disclose other traits like return format, but given the annotations, this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, minimal waste, and the primary action is front-loaded. The description achieves efficiency without sacrificing essential purpose clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, no output schema, and no nested structures, the description is extremely sparse. It lacks any mention of the required businessId, return value, error handling, or prerequisites, leaving many operational details unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate but doesn't. It only clarifies that the update is partial, which is useful, but provides no meaning for individual parameters beyond their field names. This is a significant gap for a 10-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a business record') with a specific resource. It distinguishes from sibling operations like create, delete, and get, and the phrase 'Only provided fields change' adds a precise behavioral scope that differentiates it further.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as create or get. The usage is implied by the 'update' verb, but there is no mention of conditions, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a mutation (readOnlyHint false) and idempotent. The description adds the critical behavior that only provided fields are updated, which is not captured by annotations. This helps an agent understand side effects (unprovided fields remain unchanged). However, it does not disclose return format or error conditions, which is acceptable given no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences with no filler. It front-loads the action and adds a crucial qualifier. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters and low schema coverage, the description provides the core behavior (partial update) but omits details like required productId (though schema covers it) and field semantics. It is adequate for a simple mutation but could mention that productId is required or that locationId defaults. However, the schema handles those, so the description is minimal yet not incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, and the description does not elaborate on any parameter meanings. It merely says 'update fields' without listing or explaining them. Since the schema lacks descriptions for most fields, the description should compensate but does not, leaving ambiguity about fields like availableInStore or productType meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (product's fields). It is not a tautology and distinguishes from siblings like create/delete/get by implying modification of existing records. The phrase 'Only provided fields change' adds specificity about partial updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a key usage fact—partial update semantics—but does not explicitly state when to use this tool over alternatives like ghl_create_product or ghl_delete_product. It implies usage for modifying existing products but lacks explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write, non-idempotent operation. The description adds the clarification that amount is in the smallest practical unit (typically major units) and explains the type enum values, which is useful. However, it does not disclose what happens on success/failure or whether a price is appended or replaced, so the description adds moderate value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action, and covers key behavioral details without fluff. It is concise and readable, though the amount-unit sentence could be slightly tighter. Overall it efficiently communicates the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 6 parameters (3 required) and no output schema, the description explains type and amount but omits the crucial productId parameter (even though it's in the required schema). It also does not mention what the tool returns (e.g., the created price object). The description is adequate but incomplete for an agent to fully understand the call without cross-referencing the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (3 of 6 parameters have descriptions). The description adds meaning for amount (unit clarification) and type (explicitly lists enum options with examples), which helps. However, it does not address productId (a required parameter) or locationId/currency semantics, relying on the schema for those. The description partially compensates for the coverage gap but leaves productId unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add a price to a product) and distinguishes it from sibling tools like ghl_list_product_prices or ghl_create_product. It also introduces the type and amount semantics that are not obvious from the name alone, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when adding a price to a product) but does not explicitly mention alternatives or scenarios when not to use it. It does not reference sibling tools like ghl_list_product_prices or ghl_update_product, so an agent must infer context from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and idempotentHint, and the description repeats 'Destructive' which is consistent. It adds the clarifier that it removes a task specifically from a contact, which clarifies the scope. However, it does not disclose any additional behaviors such as permissions or side effects beyond what annotations provide. Since annotations cover the key traits, this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of four words plus 'Destructive.' It is highly concise, with the primary action and target stated first, and no filler. It earns high marks for efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with two parameters, the description provides the essential information. However, the lack of an output schema means the agent does not know what the tool returns, and the description does not address this. Additionally, it does not mention any caveats like cascading effects. Given the minimal scope, it is adequate but lacks some completeness that would be expected for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, and the description itself does not elaborate on 'contactId' or 'taskId'. The parameter names are self-explanatory, but the description adds no additional meaning about formats, validation, or relationships. Given the low schema coverage, the description should compensate, but it does not, leaving the agent to infer the parameters' roles from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the target (a task from a contact). It distinguishes this from other delete operations in the sibling list (e.g., delete contact, delete note) by specifying 'contact task'. The added 'Destructive' reinforces the operation's nature. This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use guidance or alternatives. However, the naming convention and the action itself make the purpose obvious. There is no mention of when not to use it or any prerequisites. The context is implied rather than stated, so this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Behavioral transparency is reasonably covered by annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), which already indicate a state-changing operation. The description adds the detail that line items are carried over, which is helpful. However, it doesn't disclose any side effects on the estimate itself (e.g., whether it becomes void or marked as invoiced), nor does it mention any permission requirements or rate limits. Given annotations, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that leads with the action and key behavior. There is no extraneous text, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is brief and leaves out important context. It doesn't specify the return value (new invoice), nor does it mention any prerequisites like the estimate must exist and be accepted. It also doesn't note the impact on the original estimate. With no output schema, this lack of information could leave the agent uncertain about the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% – estimateId has no description in the schema, while locationId does have one. The description implicitly clarifies estimateId by mentioning 'estimate,' but it doesn't explicitly describe either parameter. It adds minimal value beyond the schema, so a score of 3 is appropriate given the moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: creating an invoice from an accepted estimate, and notes that it carries over line items. This distinguishes it from ghl_create_invoice, which creates an invoice without an estimate, and from other estimate operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (converting an accepted estimate) but does not explicitly state when not to use it or compare it to alternatives like ghl_create_invoice. It doesn't mention any preconditions beyond the estimate being accepted, and doesn't discuss cases where the estimate is not accepted or already converted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds 'single record by id' but no additional behavioral context like return format, error behavior, or auth requirements. It is consistent with annotations and adds minimal value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence with no wasted words. The action and object are front-loaded, making it instantly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id operation, this is adequate. No output schema exists, but the phrase 'fetch a single business record' implies the return is the record itself. It lacks detail about the entity type or record shape, but the tool is simple enough that nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter businessId is self-explanatory and required. Schema description coverage is 0%, so the description must compensate. Mentioning 'by id' clarifies the parameter's role, but it adds only marginal meaning beyond the parameter name and tool purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a clear resource ('business record'), and scope ('single by id'). It distinguishes from list_businesses and create/update/delete operations. Even without naming a sibling, the resource and action are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like ghl_list_businesses or other get-by-id tools. The description only states what it does, leaving the agent to infer the use case from the tool name and sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares this is a read-only operation, and the description's 'List' wording is consistent. The description adds the appointment-scoping detail but does not disclose behaviors such as pagination behavior, ordering, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It states the verb and object immediately and earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description, schema, and annotations provide enough to make a basic call. However, with no output schema, no return-format details, and no usage guidance, the description is only minimally complete rather than thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate for undocumented parameters. It provides context for appointmentId via 'calendar appointment' but says nothing about limit or offset semantics. The schema shows types and defaults, but the description adds little meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('notes attached to a calendar appointment'). This distinguishes it from related tools like ghl_list_contact_notes, since the scope is explicitly appointment-scoped rather than contact-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an agent needs notes for a calendar appointment, but it provides no explicit guidance about when not to use it or which alternative to choose. Sibling tools exist for contact notes, but no comparison or routing is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds useful context that the values are location-scoped and serve as reusable merge fields, but it does not disclose return shape, ordering, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the operation and immediately clarifies the domain term with a parenthetical. There is no filler or redundant repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, full schema coverage, and readOnlyHint/openWorldHint annotations, the description is nearly sufficient. The main missing piece is an explicit statement of the return format since there is no output schema, but this is a minor gap for a straightforward list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter, locationId, including its default behavior, so the description does not need to restate it. With 100% schema description coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with the resource 'location custom values' and clarifies what they are ('reusable merge fields used in templates/messages'), making the tool's purpose immediately clear. It also distinguishes this from related siblings like ghl_get_custom_value and ghl_list_custom_fields through the 'merge fields' framing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to choose this tool over alternatives such as ghl_get_custom_value, ghl_create_custom_value, or ghl_list_custom_fields. Usage is only implied by the verb 'List' and the resource name, with no when-to-use or when-not-to-use conditions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and openWorldHint, covering the read-only and open-ended nature of the operation. The description adds only the location scoping and downstream use of returned form ids; it does not disclose pagination behavior or response details beyond the presence of form ids.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words. The first sentence states the action and scope, and the second explains why the returned ids matter. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list endpoint with three optional parameters and no output schema, this description is largely sufficient: it identifies the resource, the location scoping, and how to use the returned ids. Pagination is implied by skip/limit in the schema, and the openWorldHint annotation covers the open-ended nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description does not compensate for the undocumented skip and limit parameters. 'List forms in a location' adds no meaningful semantics beyond locationId, which is already described in the schema. The agent gets no extra guidance on pagination or parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List forms in a location') and explains the downstream use of returned form ids for fetching submissions. This clearly distinguishes the tool from the sibling ghl_get_form_submissions, though it does not explicitly name that alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'List forms in a location. Use the returned form ids to fetch submissions' provides a clear context: call this when you need form ids to later fetch submissions. It does not state when not to use the tool or explicitly reference a sibling tool, but the intended workflow is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description is consistent with a read-only list operation. It adds location scoping and filter dimensions, but does not disclose pagination behavior, response shape, or the meaning of open-world results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler. It names the action, resource, scope, and optional filters efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only list tool, and the description covers the core action and filters. However, with no output schema and limited filter semantics, an agent still lacks detail about response data, pagination, and the exact filtering contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description adds little beyond naming type, category, and name as filters. It does not explain valid filter values, how filters combine, or pagination semantics, and category has no meaningful description either in the schema or the prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('funnels'), and adds location scoping plus optional filters. This clearly distinguishes it from sibling tools like ghl_list_funnel_pages and other list_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: whenever you need to list funnels in a location. However, it gives no explicit alternatives or exclusions, such as pointing to ghl_list_funnel_pages for page-level data, so guidance beyond the obvious is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description's 'List' action is consistent with that. However, the description adds no additional behavioral information, such as pagination behavior, result scope, or any side effects, leaving the agent to rely solely on annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It front-loads the action and resource, making it easy to parse. No unnecessary details are included, which is ideal for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with one optional parameter and no output schema, the description is adequate. It clarifies the scope (location) and aligns with the read-only annotation. While it does not describe return format or pagination, these are not critical for a basic list operation, and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, locationId, is fully documented in the schema with a description (including a default). The tool description does not mention the parameter at all, so it adds no meaning beyond what the schema provides. With 100% schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('trackable trigger links') with a location scope. It is distinct from sibling tools like ghl_create_trigger_link and ghl_delete_trigger_link, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any mention of exclusions or context. While the purpose is clear from the name, the description does not explicitly indicate when listing trigger links is appropriate, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering the safe read nature of the operation. The description adds minimal behavioral context—it does not discuss pagination, sorting, or response shape, but it does imply the response contains user IDs. This is acceptable given the annotation coverage, though more could be said about what the list returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the core purpose, the second provides actionable guidance on using the output. No wasted words, and the essential information is front-loaded. This is an exemplary level of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional param and no output schema, the description provides enough for an agent to call it and interpret the purpose correctly. It explains the output's usage, but does not specify whether the list is paginated or the exact return structure. Given the low complexity and annotation hints, this is nearly complete, but a note on response format would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter locationId is fully documented in the schema with its type, description, and default behavior. The tool description adds no additional meaning beyond reinforcing that users are scoped by location. Since schema coverage is 100%, a score of 3 is appropriate as the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists users (team members) within a location, and distinguishes itself from the single-user sibling ghl_get_user by the explicit 'list' scope and the mention of 'in a location'. The purpose is specific and unambiguous, though it does not name the alternative tool directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent how to use the returned IDs (for assignedTo/assignedUserId fields) and implies the tool is appropriate when a listing of users is needed. However, it does not explicitly contrast with ghl_get_user or provide conditions for when to prefer this tool over alternatives, leaving the selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=true, so the agent knows this is a mutating, potentially side-effecting, idempotent operation. The description adds 'starting it for them', which hints that the campaign is initiated for the contact, but it does not explain possible side effects (e.g., triggered emails) or the meaning of idempotency. It provides minimal extra context beyond the annotations and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of ten words that states the core action and its result without unnecessary words. It is front-loaded with the verb and object, and the clarifying phrase 'starting it for them' adds value without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-string-parameter tool with no output schema, the description is mostly complete. It tells the agent what the tool does, and annotations cover safety and idempotency. However, it does not mention what happens if the contact is already in the campaign, precondition requirements, or error cases. Given the simplicity, the gaps are minor but non-negligible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for contactId and campaignId, and the description does not compensate. While the parameter names are self-explanatory (IDs of contact and campaign), the description does not clarify their format, required scope, or any relationship to other data. With 0% schema description coverage, the tool description should carry more interpretive weight, but it is silent on parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'enroll' with a clear resource 'a contact into a campaign', and adds 'starting it for them' to clarify the effect. This distinguishes it from sibling tools like ghl_remove_contact_from_campaign and ghl_add_contact_to_workflow, so an agent can understand its purpose without inspecting other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you want to enroll a contact in a campaign) but provides no explicit guidance about alternatives or exclusions. It does not mention that ghl_remove_contact_from_campaign is the inverse, nor when to prefer this over ghl_add_contact_to_workflow. Usage context is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a write operation (readOnlyHint=false) and non-idempotent. The description adds the key outcome (prevents booking) but does not disclose side effects such as what happens to existing appointments, permission requirements, or whether the block can be removed. With annotations present, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, example in parentheses, and a format note. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and no output schema, the description explains the core intent but leaves ambiguities around calendar selection defaults, overlap behavior, and return value. Combined with openWorldHint=true, an agent might not fully anticipate side effects. However, required parameters are clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema documents most parameters. The description reinforces that startTime/endTime are ISO 8601 but adds no information beyond the schema. It does not clarify the optional calendarId behavior or the undocumented assignedUserId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action (block) on a specific resource (calendar time) with the outcome (can't be booked) and an example use case. This clearly distinguishes it from appointment creation tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case (blocking off time for filming/edit days) but does not explicitly compare it to sibling tools like ghl_create_appointment or ghl_get_free_slots. There is no 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-idempotent operation. The description adds no behavioral context beyond the obvious create action; it does not mention return values, side effects, permissions, or what happens after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences: one states the core action, the other flags the important date format. No redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a straightforward create operation, especially with schema and annotations present. However, with no output schema, the description should specify what the tool returns (e.g., created task object or ID) to fully support correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents 4 of 6 parameters. The description adds a concrete ISO 8601 example for dueDate, which is mildly helpful, but it does not clarify contactId, body, completed, or assignedTo beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a task on a contact' gives a specific verb, action, and target resource. It clearly distinguishes this from the sibling task/update/get/delete operations and from other contact-related creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use when creating a new task associated with a contact. It does not explicitly name alternatives or exclusion cases, but the sibling set makes the intended context reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that this is a non-read-only, non-idempotent mutation, so the description does not carry the full burden. It adds the concept of an association definition, but does not disclose what happens if the relation already exists, whether record order matters, or whether both records must exist first.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loads the core action, and contains no filler. Every sentence earns its place by conveying the operation and the source of the key parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-idempotent mutation with three required parameters and no output schema, the description is incomplete. It omits guidance on record ordering and duplicate-relation behavior, which are important for correct invocation, even though associationId provenance is helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, with locationId documented but associationId, firstRecordId, and secondRecordId left undefined. The description clarifies that associationId comes from ghl_list_associations, but it does not explain the meaning or order of firstRecordId versus secondRecordId, which is critical when creating a directional relation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it creates a relation between two records using an association definition. This clearly distinguishes the tool from siblings like ghl_delete_relation and ghl_get_record_relations, and it even tells the agent where to obtain associationId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Get associationId from ghl_list_associations' explicitly directs the agent to the correct source for a required parameter. It does not discuss when not to use the tool, but the intended usage is otherwise clear enough from the description and tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly says 'Destructive: removes the field and its stored values across records,' which goes beyond the destructiveHint annotation by specifying the exact scope of destruction (stored values across records). It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is direct and efficient. The action and key consequence are front-loaded, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one required parameter, the description covers the main consequence (removal across records). It does not mention reversibility or error conditions, but the destructive annotation and idempotentHint cover some of this. The key outcome is clearly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no information about the parameters. Schema coverage is only 50% — customFieldId has no description, and the description does not clarify its purpose or format. locationId is described in the schema but the tool description adds nothing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (delete), the resource (custom field definition), and the consequence (removes field and stored values). It clearly distinguishes from siblings like ghl_update_custom_field or ghl_get_custom_field by specifying the destructive effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention conditions like 'when you need to permanently remove a field' or mention that this is irreversible. There is no discussion of exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond the fetch operation and does not mention what happens if the ID is not found, but it is consistent and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler, directly stating the action and object. It is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource fetch with annotations covering safety, the description is nearly sufficient. It correctly uses 'definition' to disambiguate from custom values. It does not describe the return format, but no output schema is provided, and for a get-by-id operation this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: locationId has a description, but customFieldId does not. The tool description only says 'by id' and does not clarify that customFieldId is the identifier or provide format or requiredness details. Since coverage is low, the description should compensate but does not, though the parameter name is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' and a precise resource 'a single custom field definition by id', making the operation unambiguous. The word 'definition' clearly distinguishes it from fetching a custom value or listing custom fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—when you have a specific custom field ID and need its definition—but it does not explicitly mention alternatives like ghl_list_custom_fields or ghl_get_custom_value. There is no when-not-to-use guidance, but the purpose is clear enough to infer basic usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the tool returns available booking slots for a calendar/range, but it does not disclose output format, pagination, or how timezone affects slot availability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The core purpose is front-loaded, and the second sentence pragmatically clarifies the date parameter format. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The required call parameters are mostly covered by the schema, but there is no output schema, and the description does not describe the return shape or what qualifies as a 'free' slot. It also omits timezone behavior. This leaves the tool usable but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents startDate, endDate, and timezone clearly. The description adds only slight meaning for calendarId through 'for a calendar' and repeats that startDate/endDate are epoch milliseconds. With 75% schema coverage, the description is adequate but not highly additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get available booking slots for a calendar within a date range.' This clearly distinguishes it from sibling tools like ghl_create_appointment and ghl_get_calendar_events, since it focuses on availability rather than creation or existing events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool is useful: when you need free slots for a given calendar and date range. However, it offers no explicit guidance about alternatives or when not to use it, even though siblings like ghl_get_calendar_events and ghl_create_appointment exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the 'Fetch' wording aligns with that. The description adds little beyond the annotations—it does not disclose pagination behavior, date-range semantics, or result ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with an active verb and no filler. The optional filter is presented compactly without repeating parameter defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation, the description states the essence and annotations cover safety, but an agent still lacks explicit guidance on pagination, date-range behavior, and whether omitting surveyId returns all submissions. Given six optional parameters and no output schema, more context would improve call correctness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover startAt, endAt, and locationId, and constraints document page and limit. The description contributes meaning for surveyId by noting the optional filter, which compensates for the missing schema description, but it does not elaborate on how pagination or date filtering interacts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and identifies a precise resource: survey submissions for a location. It clearly distinguishes this from sibling tools like ghl_get_form_submissions by naming 'surveys' as the scope, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving survey submissions and optionally filtering to a single survey, but it never states when to prefer this over siblings like ghl_get_form_submissions. No explicit alternatives or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation by framing the operation as a read-only 'List' action. It adds useful context that the items are definitions/relationship types rather than record-level relations, but it does not disclose behavior beyond that, such as pagination limits, defaults, or whether the result set is exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant phrasing. The parenthetical adds meaningful clarification rather than repetition, and the core action and scope are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list operation with all parameters optional, the description is largely sufficient: it states what is listed and in what scope. It does not describe pagination or return shape, but the schema supplies skip/limit defaults and the annotations cover the safety profile, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; only locationId has a description in the schema. The tool description does not compensate by explaining skip or limit usage, nor does it add meaningful parameter-level semantics beyond what the schema already provides for locationId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource as 'association definitions' scoped to a location. The parenthetical further clarifies what these definitions are ('relationship types available between record kinds'), which distinguishes this from sibling tools like ghl_get_record_relations that deal with actual relations between records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool lists association definitions in a location, but it does not explicitly say when to use this versus related tools such as ghl_get_record_relations, ghl_create_relation, or ghl_delete_relation. Usage context is implied rather than stated, and no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds pagination behavior and the optional status/contact filters, which are not present in the annotations. readOnlyHint and openWorldHint already cover safety, so the description does not need to restate them, and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence front-loads the operation and scope before the optional filters. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers resource, location scope, pagination, and optional filters—enough for basic selection. It does not describe the return shape or mention the single-invoice alternative, and with no output schema these gaps make it slightly less than fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, so the description must compensate. It provides examples for status and indicates that contactId filters by contact, and 'pagination' hints at limit/offset, but it does not add detail for limit/offset semantics or the contactId format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), resource ('invoices'), and scope ('for a location'), plus optional filters. It is distinguishable from sibling invoice tools by the list operation, though it does not explicitly name ghl_get_invoice as the single-record alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context that this is the paginated listing endpoint for a location and names the available filters, so an agent can tell it is for retrieving collections rather than a single invoice. However, it does not explicitly say when to prefer this over ghl_get_invoice or mention exclusions, leaving the comparison to be inferred from the names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds slight context with 'configured', but gives no detail on pagination, ordering, or response shape. This is acceptable given annotations but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. The verb and object are front-loaded, making it immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low schema coverage and no output schema, the description is too sparse. It does not mention that productId is required, how pagination works, or what the response contains. An agent would have to guess about the return structure and parameter details, so the description is not complete enough for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only locationId has a description). The description does not explain productId, limit, or offset, despite productId being required and the other two being pagination controls. The phrase 'for a product' implies productId but does not elaborate on its meaning or the behavior of the other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('prices configured for a product'), clearly distinguishing this from siblings like ghl_list_products (which lists products) and ghl_create_product_price (which creates a price). The scoping phrase 'for a product' makes the tool's object clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys that this tool lists prices for a given product, giving clear context on when it is appropriate. However, it does not explicitly mention alternatives or when not to use it (e.g., for creating prices one would use ghl_create_product_price).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds pagination behavior and that it returns matching contacts, which adds some value but does not detail edge cases (e.g., empty results, pagination cursor usage). It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the main purpose front-loaded. No redundant words, and it covers the essential scope and features efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a read-only search tool with 5 parameters, but it lacks details on the output structure (no output schema) and specific pagination mechanics (e.g., how to use startAfter/startAfterId). An agent can likely call it correctly, but some assumptions remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema. The description mentions free-text query and pagination, aligning with the schema, but does not introduce new parameter details beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches/lists contacts in a GoHighLevel location, specifies the free-text query matches name, email, and phone, and mentions pagination. This clearly distinguishes it from sibling tools like ghl_get_contact (single contact) and ghl_create_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching contacts but does not explicitly say when to use it versus alternatives. It doesn't mention that for fetching a specific contact by ID, ghl_get_contact should be used, nor does it discuss exclusions. The context is clear but lacks explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description need not repeat safety. It adds no information about pagination behavior, defaults, or return structure beyond what the schema provides. The description is consistent with read-only intent and does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that fronts the action and filters without redundancy. Every phrase contributes: 'in a location' sets scope, and the filter list is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no output schema, and only read-only annotations, the description leaves the agent uncertain about return format, pagination defaults, and whether locationId is required (it defaults but description says 'in a location'). It does not mention that a single-get alternative exists. The definition is adequate for basic use but lacks guidance on result handling and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 56% (5 out of 9 params documented). The description clarifies ambiguous filters (e.g., 'assigned user' for assignedTo, 'free-text query' for query) and mentions location, but it omits page, limit, contactId, and pipeline specifics. It adds some semantic value but does not fully compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (Search), resource (opportunities/deals), and scope (in a location), and enumerates the key filter dimensions. This clearly differentiates it from sibling tools like ghl_get_opportunity (single fetch) and ghl_search_contacts (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing/filtering deals but does not explicitly state when to prefer this over ghl_get_opportunity (single) or ghl_create_opportunity (creation). There is no mention of alternatives or exclusions, leaving the agent to infer based on tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate a non-read-only, non-idempotent, open-world operation. The description adds the account-dependent estimate-number prerequisite and date format constraint, but it does not disclose side effects like applying saved defaults or what happens on success. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the core purpose front-loaded and the prerequisite placed immediately after. No filler, no restating of the schema, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic create flow and the estimate-number prerequisite, which is enough for simple invocations. However, given 19 parameters, openWorldHint, and no output schema, it leaves important context unstated, such as how applyDefaults affects saved settings and what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 53% schema description coverage, most parameter semantics come from the schema. The description mostly repeats what the schema already says for estimateNumber, issueDate, and expiryDate, adding only the sequencing hint 'get ... first.' It does not compensate for the undocumented optional business/contact override parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb ('Create'), resource ('estimate/quote'), target ('for a contact'), and content ('with line items'). This clearly distinguishes the tool from siblings like ghl_update_estimate or ghl_generate_estimate_number, and the parenthetical 'quote' removes ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete conditional workflow: if the account requires an estimate number, call ghl_generate_estimate_number first. This gives useful sequencing guidance, though it does not explicitly contrast this tool with update/send/delete estimate siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a write (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds genuine behavioral context beyond that: the created artifact 'can fire automations on click,' signaling downstream side effects consistent with openWorldHint=true. It does not disclose what the creation call itself returns, however.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 20-word sentence with the action and resource front-loaded. Every phrase earns its place: resource type, redirect behavior, and the automation side-effect. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool (3 flat params, no nested objects) the core purpose is well covered. However, with no output schema, the description should indicate what the agent receives in return — especially the generated link URL, which is the entire product of this tool — and it does not. This is a meaningful operational gap for an agent that needs to hand the resulting link to a user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: redirectTo and locationId have schema descriptions, but the required `name` parameter is undocumented in both the schema and the description. The description only echoes redirectTo's role ('redirects to a destination URL') without adding naming conventions, length constraints, or uniqueness guidance, so it fails to compensate for the missing `name` semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names a specific verb ('Create') and a concrete resource ('trackable trigger link'), and explains what that resource is — a redirecting link that fires automations. This clearly differentiates it from sibling tools like ghl_list_trigger_links and ghl_delete_trigger_link, and from the many other ghl_create_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the use case implicitly ('can fire automations on click' tells an agent when such a link is wanted), but it never explicitly states when to use this tool versus alternatives or mentions any exclusions. Disambiguation from list/delete trigger-link siblings relies on their names rather than on guidance in this description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description emphasizes permanence ('cannot be undone'), which adds value beyond the annotations that already indicate destructiveHint=true and idempotentHint=true. This reinforces the irreversible nature of the operation, which is useful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundant wording. The critical information ('Permanently delete', 'destructive', 'cannot be undone') is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete operation, the description covers the essential purpose and destructiveness. It does not explain error handling or edge cases, but given the lack of an output schema and the tool's simplicity, the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes contactId fully as 'The contact id to delete' (100% coverage), so the baseline is 3. The description adds no additional parameter-related information, which is acceptable given the high schema coverage and single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Permanently delete') and the resource ('a contact'), with no ambiguity. It distinguishes itself from sibling tools by specifying the target resource explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like ghl_delete_relation or ghl_delete_contact_task. The description does not mention context, exclusions, or alternatives, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only and open-world behavior. The description adds useful context about location scoping, pagination, and filtering, but does not go beyond that to mention output shape, sorting, or pagination behavior details. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence packs the resource, synonym, location scope, pagination, and optional filters. Every word earns its place and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool, the description provides enough to make a correct call: location, pagination, and available filters. It lacks explicit output/return-shape guidance and usage-vs-alternatives, but annotations cover the safety profile and the schema covers default values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 40%, so the description partially compensates by mentioning pagination and contact filtering. It clarifies that 'contactId' is used for filtering by contact, which the schema leaves undocumented. However, limit/offset semantics are only implied by 'pagination'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and names the resource ('estimates (quotes)') with explicit scope ('for a location'), pagination, and optional filters. This clearly distinguishes it from invoice and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the basic usage evident: list estimates for a location, with optional status or contact filtering. However, it does not state when to prefer this over alternatives or mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds a small behavioral detail about using returned survey IDs to fetch submissions, but it does not mention pagination, return format, or other runtime behavior. With annotations carrying the main burden, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The first states the core operation, and the second provides the follow-up action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description only hints at returned survey IDs but does not describe the list envelope, pagination behavior, or response shape. Schema defaults help with skip and limit, but the description remains minimal. It is adequate for a simple read-only list tool but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; only locationId has a description. The tool description does not compensate by explaining skip or limit semantics, and it only loosely mentions location without adding detail beyond the schema. This is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List surveys in a location.' It also distinguishes itself from submission-fetching tools by saying 'Use the returned survey ids to fetch submissions,' which differentiates it from ghl_get_survey_submissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: list surveys first, then use the returned IDs to fetch submissions. It does not explicitly list when not to use this tool or name alternative tools, but the intended workflow is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a write operation (readOnlyHint=false) and that it is idempotent. The description adds the broad scope behavior of removing from all campaigns when campaignId is omitted, which is useful context, but it does not disclose potential side effects or what happens to the contact/campaign relationship beyond the removal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and includes the most important optional behavior. Every phrase earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool with annotations covering idempotency and write behavior, the description is adequately complete. It lacks explicit alternative guidance and does not clarify that the contact itself is not deleted, but this is largely covered by the tool name, schema, and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents campaignId and its omission behavior, so the description mostly reinforces that. The description implicitly clarifies that contactId refers to the contact being removed, which helps compensate for the missing contactId description, but it adds little beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Remove'), a specific resource ('contact'), and the target context ('campaign'), including the important variation of removing from all campaigns when no campaign ID is given. This distinguishes it from sibling tools like ghl_add_contact_to_campaign and ghl_remove_contact_from_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the verb and resource, but the description does not explicitly say when to use this tool versus alternatives, nor does it mention related tools such as ghl_add_contact_to_campaign or ghl_remove_contact_from_workflow. There is no when-not-to-use or exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true. The description states it 'Returns conversation threads with their ids and last-message info,' which adds behavioral detail beyond the schema and is consistent with a read-only operation. It does not contradict annotations. While it doesn't mention rate limits or auth, the read-only nature is already covered. The description adds useful context about the return payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. It states the action and resource first, then the optional filter, then the return info. Two sentences with no fluff. Every word earns its place, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the return value ('conversation threads with their ids and last-message info'), which is important since there is no output schema. It also clarifies the scope (location) and optional contact filter. Pagination and limit behavior are not covered, but the schema provides defaults and bounds. Given the tool's simplicity and annotations, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (limit lacks a description but has default/max/min). The description mentions location and contact filter, which are already described in the schema, so it adds little beyond what the schema provides. It doesn't clarify the 'limit' parameter or elaborate on 'query' semantics. Given the high coverage, the description is adequate but not compensating for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search conversations in a location, optionally filtered to a contact.' It names the resource (conversations) and the action (search), and specifies the returned data (ids and last-message info). While it doesn't explicitly contrast with sibling tools like ghl_get_messages, the verb and resource are specific enough to distinguish it. A minor gap is that it doesn't clarify how this differs from getting a single conversation, but it's a clear and actionable description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context (search within a location, optional contact filter) but does not explicitly state when to use this tool over alternatives or when not to use it. It implies this is for finding conversations, but there is no explicit 'use this instead of X' guidance. The context provided is helpful, but exclusions and alternative routing are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, openWorldHint=true, and idempotentHint=true, but the description adds the key behavioral detail that only provided fields are changed, i.e., a partial update rather than a full replacement. This is valuable context beyond the annotations. It does not contradict any annotation and clarifies a core side-effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and includes the critical behavioral constraint. There is no redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with 7 parameters and no output schema. The description covers the essential purpose and partial-update behavior, and annotations provide safety and idempotency hints. However, it omits details like error handling (e.g., what happens if the contact doesn't exist) and any restrictions on specific fields, which would be helpful for an agent but are not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 29% (2 of 7 properties have descriptions). The tool description adds nothing specific about parameter meanings or formats—it only states a general partial-update rule. For a tool with low schema coverage, the description should compensate, but it does not, leaving semantic gaps for fields like email, phone, and names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Update fields on an existing contact.' It distinguishes from create (which implies a new record) and from read/delete operations. The phrase 'existing contact' and 'Only provided fields are changed' adds specific semantics that separate it from full replace operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing contact and that only supplied fields are changed, which is a partial-update guideline. However, it does not explicitly mention alternatives like ghl_create_contact for new records or ghl_add_contact_tags for tag-specific behavior, nor does it exclude them in certain contexts. The guidance is present but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description doesn't contradict them. It adds minimal behavioral context (mutates an appointment) beyond the basic operation, but doesn't discuss side effects, permissions, or error conditions. With annotations present, this is adequate but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. It efficiently communicates the purpose and an example, earning its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with 3 parameters and annotations covering mutation, the description is mostly complete. It lacks explicit differentiation from ghl_create_contact_note and doesn't describe the appointmentId parameter, but these are minor gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 'body' and 'userId' but not 'appointmentId'. The description doesn't clarify parameters beyond the schema; 'appointmentId' is implied by 'calendar appointment' but not explicitly described. With 67% schema coverage, the description should compensate, but it doesn't add value for the missing parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Add') and resource ('a note to a calendar appointment'), with an example ('outcome of a shoot/call'). It is distinct from the sibling ghl_create_contact_note because it scopes to appointments, not contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate use case (adding notes to appointments) and gives a concrete scenario. It does not explicitly exclude alternatives like contact notes, but the specificity makes the intended use clear. No explicit when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent operation, so the description does not need to restate that. It adds a useful API requirement: option-based data types require the options array. It does not disclose side effects such as persistence, irreversible creation, or permission requirements, but this is acceptable given the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary action is front-loaded, and the only additional sentence states a conditional requirement that directly affects successful invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the schema and annotations, is sufficient for an agent to make a basic valid call: provide name, dataType, and options when needed. However, it does not describe the return value, any lifecycle implications, or the meaning of position/placeholder fields, and there is no output schema to fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes most parameters, with 71% coverage. The description adds meaningful semantic value by enumerating exactly which data types are option-based (SINGLE_OPTIONS, MULTIPLE_OPTIONS, RADIO, CHECKBOX), which is not derivable from the raw enum alone. It does not clarify the omitted position and placeholder parameters, but the key non-obvious parameter rule is covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a custom field definition.' Using 'definition' distinguishes this from sibling custom-value tools, and 'Create' clearly separates it from list/get/update/delete custom-field tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage by stating it creates a custom field definition and gives a conditional instruction for option-based types. However, it does not explicitly contrast this tool with update, delete, list, or custom-value alternatives, so the usage context is implied rather than fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent operation. The description adds useful context: a product is not usable on invoices/estimates until prices are added. It does not disclose other side effects, permissions, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the primary action front-loaded and the follow-up workflow stated efficiently. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides the essential create-then-price workflow, which is helpful. However, with no output schema, it omits mention of the returned product ID that would likely be needed to call ghl_create_product_price, leaving a moderate completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level guidance. Schema coverage is 60%, covering name, locationId, and productType, but availableInStore and description are undocumented. The missing parameters are relatively simple, but the description does not compensate for them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete action, 'Create a product,' and clearly identifies the resource. It also names the exact follow-up tool, ghl_create_product_price, distinguishing product creation from price creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent to use ghl_create_product_price after creating and explains why that step is needed for invoices/estimates. It does not mention when not to use the tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the description does not need to restate that this is destructive. It adds useful scoping by limiting deletion to scheduled or draft posts, but 'Destructive' is redundant with the annotation and no additional behavioral detail is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, stating the action and scope immediately. The standalone 'Destructive.' is redundant with the annotations and adds little value, but overall the description is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the required postId is clear, the scope is stated, and annotations cover the destructive and idempotent behavior. It does not describe return values or error behavior, but that is a minor gap for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents locationId, and postId is self-explanatory from the tool name. The description adds no parameter-level meaning, but with 50% schema coverage and the postId being intuitive, the lack of additional parameter detail is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action 'Delete' and the resource 'social post', and further specifies 'scheduled or draft'. This makes it easy to distinguish from siblings like ghl_create_social_post, ghl_get_social_post, and ghl_list_social_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'scheduled or draft' provides useful context about which posts this tool applies to, implicitly excluding published posts. However, it does not explicitly reference alternative tools or state when another tool should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the operation as destructive, but the description adds useful context by stating that deletion also removes the tag from records. It does not contradict the annotations and provides a meaningful behavioral consequence beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It front-loads the main action and then adds the important destructive consequence in a clear, efficient way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter deletion tool, the description together with annotations covers the essential behavior, including the destructive effect. The main missing piece is more explicit guidance on where to obtain the tagId, but this is not critical for an experienced agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, and the description does not clarify the required tagId parameter beyond echoing the word 'tag'. locationId is already described in the schema, but tagId remains under-documented and the description does not compensate for that gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete a tag') and a clear scope ('from the location'), then clarifies the real-world effect ('removes it from records'). This clearly differentiates it from sibling tag operations like ghl_create_tag and ghl_update_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a tag should be permanently deleted and removed from records. However, it does not explicitly state when to prefer alternatives such as removing a tag from a contact or deleting other entity types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations include readOnlyHint=true, which already informs the agent this is a safe read operation. The description consistently says 'Fetch', reinforcing that. The openWorldHint is also covered. Since annotations carry the behavioral safety profile, the description adds minimal extra detail beyond the action, which is appropriate for a simple get.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no redundancy. The key information is front-loaded: what it does and how. It is appropriately sized for a simple fetch tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only, no output schema), the description covers the essential action and input. It does not specify the response format or error behavior, but those are often implied for standard get-by-id operations. The annotations further cover safety. It is nearly complete for its complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. However, it merely says 'by id' which simply restates the parameter name 'opportunityId'. It does not explain the expected format, origin, or any semantics beyond what the parameter name already conveys. This adds no meaningful value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fetch a single opportunity (deal) by id' clearly states the verb (Fetch), resource (opportunity/deal), and the specific retrieval method (by id). It effectively differentiates from sibling tools like ghl_search_opportunities (which searches) and other get-by-id tools 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by id' implies usage when the caller already knows the opportunity ID, which is a clear usage context. However, it does not explicitly mention alternatives like searching when the ID is unknown, nor does it state when not to use this tool. The guidance is adequate but not explicit about exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, idempotent operation. The description adds the key behavioral detail that only provided fields change, preventing the agent from assuming a full replacement. It does not describe side effects like option handling, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences. The main action is front-loaded and the second sentence clarifies a critical behavioral constraint without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and partial-update behavior, but it omits when-to-use guidance, any mention of required identifier beyond the schema, and return/error behavior. Since this is a mutation tool with 6 parameters and no output schema, slightly more context would be valuable, though it is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is very low (17%), so the description carries some burden. It adds general patch semantics but does not explain individual parameters like options or placeholder. However, the parameter names are mostly self-explanatory and customFieldId is clearly the target identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('a custom field definition'), and the phrase 'Only provided fields change' adds important partial-update semantics. This distinguishes it from sibling tools like ghl_create_custom_field and ghl_delete_custom_field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when an existing custom field definition needs modification, but it does not explicitly mention alternatives such as create or delete custom field tools, nor does it provide conditions like 'use create for new fields.' The intended usage is mostly inferred from the name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true, so the mutation/safety profile is covered. The description adds the behavioral effect that enrolling triggers the workflow for that contact. It does not elaborate on idempotency behavior, duplicate enrollments, or side effects beyond triggering, but does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The action and effect are stated first, followed by a useful prerequisite pointer. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple enrollment action with two required IDs and an optional timestamp, the description is nearly complete. It tells the agent how to obtain one required ID, and the output schema is absent so return values need not be explained. A minor gap is the lack of explicit differentiation from campaign enrollment, but this is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate. It adds meaning to workflowId by pointing to ghl_list_workflows, while eventStartTime is already described in the schema. contactId remains self-explanatory by name but has no additional semantic guidance. Partial compensation for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Enroll') and resource ('a contact into an automation workflow'), and clarifies the effect ('triggering it for that contact'). It clearly distinguishes from the sibling remove_contact_from_workflow and is specific enough not to be confused with campaign enrollment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete usage pointer: 'Use ghl_list_workflows to find workflowId.' It provides clear context that this is for automation workflows, though it does not explicitly state exclusions such as 'use add_contact_to_campaign for campaigns' or 'use remove_contact_from_workflow to undo enrollment.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a non-read-only, non-idempotent, open-world operation. The description adds the prerequisite of checking free slots and clarifies the time format, but does not disclose additional side effects such as conflicts, cancellations, or external calendar behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core purpose is front-loaded, and the critical prerequisite and time-format clarification are included without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with an existing schema and annotations, the description provides the essential invocation context: what it does, what format the times use, and the recommended preceding tool. It lacks details about return values or optional-field behavior, but those are not required to make a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds a concrete ISO 8601 example for startTime/endTime, which is helpful beyond the schema's brief descriptions. However, it does not explain the semantics of required parameters like calendarId or contactId beyond the natural-language context, nor optional fields like assignedUserId or appointmentStatus.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Book an appointment') and the target resource ('on a calendar for a contact'). This clearly separates it from appointment-related siblings like ghl_get_appointment, ghl_update_appointment, and ghl_delete_appointment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to call ghl_get_free_slots first, establishing a clear prerequisite workflow. It does not enumerate when not to use this tool versus update/delete, but the context is strong enough for correct routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint:false, openWorldHint:true, and idempotentHint:false, so an agent knows this call mutates state, may have side effects beyond provided params, and is not safe to repeat. The description adds the '(deal)' domain clarification and pipeline-stage context but discloses no additional behavioral traits (e.g., duplicate creation on retries or auth requirements) — acceptable given the annotated safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler: the first states the action and scope, the second states the prerequisite call. Information is front-loaded with verb, resource, and context appearing immediately, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with 8 parameters, 100% schema coverage, and annotations declaring read-write, open-world, non-idempotent behavior, the description covers the critical path: what is created and which tool to call first. The only gap is silence on what the call returns, which is minor for a create tool whose annotations already establish the side-effect profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter has a meaningful description, so the schema carries the explanatory burden, yielding the baseline 3. The description adds the dependency relationship between pipelineId/pipelineStageId and ghl_get_pipelines, which is useful, but provides no per-parameter meaning beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Create a new opportunity (deal) in a pipeline stage' — a specific verb (create), resource (opportunity), and context (pipeline stage), with the parenthetical '(deal)' anchoring domain terminology. The verb clearly distinguishes it from sibling tools like ghl_update_opportunity, ghl_get_opportunity, and ghl_search_opportunities, so an agent can select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit prerequisite: 'Use ghl_get_pipelines first to obtain valid pipelineId and pipelineStageId values,' which both instructs the agent and explains why the prerequisite matters. It does not, however, state when-not-to-use this tool versus alternatives (e.g., ghl_update_opportunity for modifying an existing deal), stopping short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only and side-effect-free nature of the tool. The description adds the purpose of finding a calendarId, but does not disclose any additional behavioral traits such as pagination, sorting, or error behavior. Since the safety profile is covered by annotations, a 3 is appropriate—it adds some contextual value but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero waste. The primary action is front-loaded, and the second sentence provides clear, actionable guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with a single optional parameter, the description covers the essential use case and purpose. Annotations cover the read-only and open-world aspects. It does not mention return format or pagination, but these are reasonable implicit expectations for a list tool. The description is adequately complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, locationId, is fully described in the schema with its purpose and default value. With 100% schema description coverage, the description does not need to add further explanation. The tool description does not add any extra semantics beyond the schema, so the baseline score of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('calendars'), and a clear scope ('for a location'). It also explicitly mentions the intended use case of finding a calendarId for booking and availability lookups, which distinguishes it from related sibling tools like ghl_get_calendar_events or ghl_block_calendar_slot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear 'when to use' instruction: 'Use this to find a calendarId for booking and availability lookups.' It implies the tool is a prerequisite step for booking/availability, which guides the agent. However, it does not explicitly state alternatives or when not to use it, though the naming convention among siblings suggests the distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the behavioral nuance that the response includes custom fields and tags, which is valuable beyond the schema (which only lists the input parameter). This provides additional context about the returned data without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with no wasted words. It front-loads the core action ('Fetch a single contact by id') and then includes the key return details ('including custom fields and tags'). Perfectly concise for the level of complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool simplicity (1 parameter, no output schema, annotations cover safety), the description is complete enough for an agent to call it correctly. It communicates the essential return details (custom fields, tags). Minor omissions like authentication requirements or pagination are not necessary for a single-record fetch, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the only parameter contactId has a description). The description does not add deeper meaning about the parameter (e.g., format, required format, or source). It only says 'by id', which is implicit in the schema. The baseline of 3 is appropriate since the schema already documents the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fetch'), a specific resource ('a single contact'), and the scope ('by id, including custom fields and tags'). It distinguishes itself from siblings like ghl_search_contacts (search vs. retrieve by id) and ghl_get_business (different entity). An agent can immediately identify what this tool does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need a single contact by ID, this is the tool) but does not explicitly state when to prefer it over alternatives or when not to use it. It does not mention, for example, that ghl_search_contacts should be used when the ID is unknown. While the context is clear, explicit routing guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It adds the useful fact that the output includes stages and that the tool is a discovery aid. However, it does not disclose any potential pagination, limits, or ordering behavior, which would be helpful for a list tool. With annotations covering the read-only aspect, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The core function is front-loaded, and the usage purpose is given immediately after. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional param and safe read annotations, the description gives enough: it states what is returned and why to use it. The absence of an output schema is mitigated by the explicit mention of pipelineId and pipelineStageId discovery. Nothing critical about correct invocation is missing, though a hint about response structure would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the only parameter locationId is well described with a default and explanation. The tool description's phrase 'for a location' merely echoes the schema. It adds no new meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a precise resource ('opportunity pipelines and their stages'), and the scope ('for a location'). It also names the practical purpose ('discover pipelineId and pipelineStageId values needed by other tools'), which clearly differentiates it from any sibling tool—there is no other pipeline-listing sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use the tool: when pipelineId and pipelineStageId values are needed by other tools. It gives clear context (for a location) but does not mention explicit exclusions or alternatives. Since no sibling covers pipelines, the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and non-exhaustive nature of the operation. The description adds the location scoping and the fact that these are company records, but it does not describe pagination, sorting, or response shape, which would add more 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence that front-loads the action and resource, then narrows the scope. There is no redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional, well-documented parameter and readOnly/openWorld annotations, the description is largely sufficient. It could mention that the result is a collection or note pagination, but the name and phrasing already convey the list semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: locationId is already documented as 'GHL Location (sub-account) ID. Defaults to GHL_LOCATION_ID.' The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('business (company) records'), and a scope ('in a location'). It is immediately distinguishable from siblings like ghl_get_business by the plural 'list' and the location qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for retrieving multiple business records within a location, while ghl_get_business is available for a single record. It does not explicitly name alternatives, but the context is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is conveyed. The description adds the note about using the campaign id with another tool, which is not behavioral in itself. It does not disclose additional behavioral traits such as default filtering, pagination, or result size, but given the simple list operation and the annotations, the description adds some value without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The primary action is front-loaded, and the second sentence adds a practical downstream usage note. Every word earns its place; it is maximally concise while still being informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters, no required parameters, no output schema, and read-only annotations), the description is nearly complete. It tells the agent what the tool does and how to use the results (with ghl_add_contact_to_campaign). It does not describe the exact return structure, but since there is no output schema and the tool name implies a list, this is a minor gap. Overall, it is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'status' and 'locationId' are described in the schema, including the default for locationId. The description does not add extra parameter-level meaning beyond what the schema already provides. It mentions 'in a location' but that is already implied by the locationId parameter. Baseline 3 is appropriate when the schema covers the parameters fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a clear resource ('marketing campaigns'), and a scope ('in a location'). It is unambiguous and distinguishes itself from sibling tools by clearly naming the resource and the related action (using a campaign id with ghl_add_contact_to_campaign). No ambiguity remains about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: it tells the agent that the campaign ids obtained here are meant to be used with ghl_add_contact_to_campaign, which helps in chaining tools. It does not explicitly mention alternatives or exclusions, but the tool name and context make the primary use case clear. This is more than implied usage; it gives a concrete downstream action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the read-only nature and potential for unbounded results. The description adds the useful behavioral detail 'newest first' (ordering). It does not explain pagination or response structure, but for a simple read operation this is adequate. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that immediately states the action and ordering. No fluff, perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema) and supportive annotations, the description explains the core behavior and ordering. It does not describe the return payload structure, but for a list operation that may be acceptable since the agent only needs to invoke it correctly. Still, there is no mention of potential pagination or limits, which could matter for 'all notes'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single contactId parameter. The phrase 'notes logged on a contact' implies contactId identifies the contact, but it does not explicitly state that or provide format details. This is weak compensation for the zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' with a specific resource 'all notes logged on a contact' and adds ordering 'newest first'. This distinguishes it from sibling tools like ghl_get_contact_note (single note) and ghl_list_contact_tasks (different resource). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you need all notes for a contact, as opposed to a specific note (get_contact_note) or creating/updating notes. However, it does not explicitly name alternatives or state when not to use it, so the guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful scope and capability context, but it does not disclose return format, pagination semantics, or any API-specific behaviors beyond what the parameter names suggest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the core resource first and then the relevant capabilities, making it easy to scan and parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with no required parameters, the description is mostly sufficient: schema defaults, enums, and the list-focused wording fill in most invocation needs. The main gap is explicit sorting/return-value detail, but this is a minor omission given the self-explanatory parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 43%, and the description partially compensates by framing limit/offset as 'pagination', query as 'search', and type as a 'type filter'. However, it omits sorting behavior for sortBy/sortOrder and leaves several parameter semantics primarily to inference from names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('List') and resource ('files/folders in the location's Media Library'), and adds the key capabilities of pagination, search, and type filtering. This clearly distinguishes it from sibling media tools like ghl_upload_media_by_url and ghl_delete_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this when enumerating files or folders in the location's Media Library. It does not explicitly name alternatives or when-not-to-use conditions, but there is no competing media-list sibling, so the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the note about using the schema key with record tools, which is useful but not a deep behavioral disclosure beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, with the core purpose in the first and a practical usage hint in the second. No filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter and no output schema, the description is adequate. It covers what the tool does and how to use the result, though it does not mention pagination or limits, which is acceptable for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the locationId parameter is fully documented in the schema. The description does not add any parameter-specific details beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('custom object (and standard object) schemas defined in a location'), clearly distinguishing it from sibling tools like ghl_get_object_schema. The scope (both custom and standard) adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting the returned schema key is used with record tools, implying a workflow. However, it does not explicitly state when to prefer this over ghl_get_object_schema or other alternatives, nor does it mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful scoping ('Social Planner') and purpose ('use returned account ids when creating a post'), but does not disclose additional behavioral details such as pagination or response structure. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. The primary action is stated first, and the second sentence provides the key downstream usage. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, read-only annotations, and no output schema, the description is nearly complete. It explains the scope and the intended use of the result. A brief note on what fields are returned beyond ids would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole locationId parameter is already self-explanatory ('GHL Location (sub-account) ID. Defaults to GHL_LOCATION_ID.'). The description does not add meaningful parameter details beyond the schema, which is acceptable given the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('social media accounts connected to the location's Social Planner'). It also explains the output's downstream purpose (account ids for creating a post), which distinguishes it from sibling tools like ghl_list_media or ghl_list_social_posts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for accounts connected to the Social Planner and the returned ids are meant to be used when creating a post. This implies when to use the tool, though it does not explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's main behavioral contribution is clarifying that it lists recurring subscriptions specifically (not all subscriptions). It does not disclose details like whether canceled subscriptions are included, ordering, or pagination behavior—though limit/offset parameters hint at pagination. Overall, the description adds some context beyond annotations but not rich behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core action and scope, then adds the optional filter. Every word is necessary; there is no fluff or redundancy. It is efficient and easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 0 required, no output schema), the description covers the essential use case and filter option. The schema carries details like defaults and limits for pagination. However, it doesn't mention the default location behavior (env var) or what fields are returned, but since there's no output schema, the description is reasonably complete for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that contactId is a filter and that locationId scopes the list to a location, but it does not explain limit/offset beyond what the schema encodes. With only 25% schema description coverage (only locationId has a schema description), the description partially compensates but leaves pagination parameters undocumented in prose. The added value is modest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recurring subscriptions per location, with an example (retainers). It distinguishes from singular retrieval tools like ghl_get_subscription and other list tools (invoices, products). The verb 'List' plus the resource and scope makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on when to use it: to list recurring subscriptions for a location, with optional contact filtering. It implies this is for multiple subscriptions rather than a single one, but it doesn't explicitly name alternatives like ghl_get_subscription for when a specific ID is known. Still, the scope and filter are clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, covering safety and possible incompleteness. The description adds value by specifying that the tool surfaces failed or refunded charges, which is behavioral detail beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero clutter. The purpose and use case are front-loaded, making the description immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description does not explain the return format or fields. It also omits details about how contactId filters results and the default behavior of locationId (which is in the schema). The description is adequate for a basic list operation but lacks important operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only locationId has a description). The description does not mention limit, offset, or contactId, or their purpose. It fails to compensate for the low schema coverage, leaving contactId and the pagination semantics unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (payment transactions), and the scope (for a location). It adds specific use cases: reconciling revenue and spotting failed or refunded charges. This distinguishes it from sibling list tools like invoices or orders, as 'payment transactions' is a distinct concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool (reconciling revenue, spotting failed/refunded charges). It does not explicitly mention alternatives or when not to use it, but the stated use cases give sufficient direction for an agent to select it over other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and openWorldHint=true, so the action is known to be mutating and have external effects. The description adds value by explicitly stating 'this emails/texts the customer,' which reveals the specific external communication side-effect beyond the annotation hints. It does not detail potential consequences like duplicate sends or costs, but with annotations covering the overall openness, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The primary purpose is front-loaded, and the outward-facing note adds critical context in a compact second sentence. Every word earns its place; this is an exemplar of concise description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a send action with five params (one required) and no output schema, the description covers the essential purpose and the external impact. It does not mention the ability to test-send via liveMode or the need for a valid contact channel, but those are conveyed in the parameter descriptions. It is complete enough for an agent to invoke correctly, with minor gaps around prerequisites and post-send behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 80% of parameters with descriptions (action, userId, liveMode, locationId), leaving only estimateId undocumented. The description does not add parameter-specific insights, but the schema already provides adequate semantics. Since coverage is high, the baseline of 3 is appropriate; the description would need to compensate for gaps but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send an estimate to the contact') and specifies the outward-facing nature (emails/texts the customer). This distinguishes it from other send tools like ghl_send_invoice or ghl_send_message, which target different resources. The verb and resource are precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context (send to contact, outward-facing) but does not explicitly state when to use this tool versus alternatives such as ghl_send_invoice or ghl_send_message. It lacks explicit 'when to use' or 'when not to use' guidance, though the tool name and summary imply the use case. The context is clear enough for basic selection, but exclusions are not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating operation (readOnlyHint=false) and non-idempotent. The description adds valuable context that sending is outward-facing and results in emails/texts to the customer. However, it does not disclose that repeated sends will deliver duplicate messages or that liveMode=false triggers a test send without charging, though the latter is partially covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant wording. It front-loads the core action and resource, then provides a brief note about the outward-facing nature. Every word earns its place, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple send operation with 5 parameters and 80% schema coverage, the description is adequate. It confirms the invoice must already exist and explains the external effect. It does not mention what the response will indicate or the default behavior of liveMode, but the schema covers these details, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, and the parameters include their own descriptions for action, userId, liveMode, and locationId. The description does not add any parameter-specific details, relying on the schema to explain them. This meets the baseline for high coverage without needing additional explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Send/deliver an existing invoice to the contact via the configured channel(s).' It identifies the resource (existing invoice) and the action (send), and distinguishes it from related invoice operations like creating, listing, or voiding. The additional phrase 'This is outward-facing: it emails/texts the customer' reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when an invoice has already been created and needs to be delivered to the customer. It does not explicitly mention alternatives or exclusions (e.g., use ghl_send_estimate for estimates, or create_invoice first), but the context is clear enough for an agent to select it appropriately for sending an existing invoice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal annotations, the description discloses important behavior: the invoice is created in draft status, business details are pulled from env vars or overrides, and contact details are auto-filled from the contact record. This is meaningful transparency for a create operation. It omits return-value and error behavior, but the core side-effect profile is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The main purpose is front-loaded, followed by data-source behavior and the downstream delivery step. Every sentence earns its place and avoids repeating what the input schema already says.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential draft-invoice workflow and key data-source behavior, but with no output schema, it does not state what the tool returns, such as the created invoice ID or object, which an agent needs to use the result. With 18 parameters and a nested items array, a bit more detail about optional overrides and return behavior would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 56%, so the description needs to compensate. It adds useful high-level meaning: line items need name/qty/price, business details come from env vars with businessName/businessPhone overrides, and contact details are auto-filled. However, several undocumented parameters like contactEmail, contactPhone, businessAddress, businessLogoUrl, and businessWebsite are only implied, not explicitly mapped.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'Create a draft invoice for a contact.' It explicitly calls out draft status, distinguishing the tool from invoice delivery, voiding, and deletion siblings. The phrase 'use ghl_send_invoice to deliver it' further disambiguates the invoice lifecycle.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the intended workflow: create a draft invoice first, then use ghl_send_invoice to deliver it. It gives practical context about data sources and contact auto-fill. It does not explicitly contrast invoice creation with estimate creation, but the draft-then-send sequence provides clear operational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint and openWorldHint. The description adds the 'newest first' ordering behavior, which is a useful trait beyond the annotations. It does not describe pagination or response format, but the annotation coverage reduces the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The core action and ordering are front-loaded, and the pointer to a sibling tool is concise and useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the required input (conversationId) and tells where to get it, and annotations cover read-only safety. It does not mention the return structure, which would be helpful given no output schema, but overall it is largely adequate for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only indirectly references conversationId by telling how to find it. It does not explain the limit parameter's purpose or constraints, leaving a semantic gap for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and resource ('messages within a conversation thread'), and adds 'newest first' as a specific behavior. It also differentiates from siblings by pointing to ghl_search_conversations to find a conversationId, making its purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly directs the agent to use ghl_search_conversations to find a conversationId, which is a clear prerequisite and alternative pointer. However, it does not explicitly mention when not to use this tool (e.g., when sending a message), so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the location-scoping behavior, but does not disclose traits like pagination, ordering, or response shape, which is acceptable for a simple list but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word contributes to identifying the operation, resource, and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is intentionally simple: one optional parameter, fully documented in the schema, with read-only annotations. The description adequately completes the picture by clarifying that this lists tag definitions, not tags attached to entities, so an agent has enough context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the locationId parameter is fully documented with its default value. The description's phrase 'in a location' broadly aligns with the parameter but adds no new semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a specific resource ('all tags'), and a clear scope ('defined in a location'). It distinguishes this from sibling tag-write tools like create/update/delete tag and from contact-tag assignment tools like add_contact_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's use case is clear: retrieve the full set of tag definitions for a GHL location. It does not explicitly name alternatives or exclusions, but the resource and scope are precise enough that an agent can infer when this is the appropriate read tool among the tag-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and idempotentHint=true, so the mutation and safe-repeat behavior are known. The description adds a key behavioral trait beyond annotations: it explicitly guarantees existing tags are preserved, which prevents an agent from assuming the operation replaces the tag list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence of thirteen words, front-loaded with the action and the necessary nuance. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures the operation's core input and behavior, supplemented by annotations covering idempotency and mutation. The absence of an output schema is not addressed, and edge cases like duplicate tags or non-existent contacts are not described, but the tool is simple enough that these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; the 'tags' parameter has a schema description but 'contactId' does not. The description clarifies that contactId refers to the target contact, but it does not specify whether tag entries are names or IDs, so it provides only partial compensation for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('tags to a contact'), and the clause 'without removing existing tags' distinguishes the additive operation from any replace-style update. This clearly separates it from tag-management siblings like ghl_create_tag or ghl_update_tag, which operate on tag definitions rather than contact-tag associations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case: adding tags to a contact while preserving existing ones. It does not explicitly name alternatives or state when not to use this tool, so it falls just short of full explicit routing, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint=true already communicates that this operation is destructive, so the description's 'Destructive.' adds little beyond the structured data. It does clarify that the note is deleted 'from a contact,' which helps scope the side effect, but it does not disclose further details such as irreversibility or cascading effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one action sentence plus a one-word destructive warning. There is no fluff, and the key information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter delete operation with annotations already conveying destructive and idempotency hints, the description covers the essential behavior. It does not provide guidance on sourcing the IDs, but the low complexity makes this a minor gap rather than a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must convey parameter meaning, and it does: 'a note' maps to noteId and 'from a contact' maps to contactId. It does not explain how to obtain valid IDs or whether contactId must be the note's owning contact, but the basic semantic roles are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a note from a contact.' This clearly distinguishes it from sibling delete tools such as ghl_delete_contact and ghl_delete_appointment, which target different resources. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: use this tool when you need to delete a note belonging to a contact. It does not explicitly name alternatives or exclusions, but the resource-specific phrasing provides enough guidance given the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating no mutation. The description adds valuable context: it explains that the tool generates a sequential number and is needed as a prerequisite for estimate creation in certain accounts. This goes beyond the annotation by clarifying the purpose and typical invocation pattern, without contradicting the read-only hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the primary action and then providing a crucial usage note. Every word contributes to clarity, with no fluff. It is efficiently structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (single optional parameter, no output schema). The description covers the key purpose and when to call it. A minor gap is that it doesn't specify the return format (e.g., a string with the number), but given the tool's simplicity and annotations indicating read-only, this is acceptable for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the only parameter, locationId, is already described with defaults. The description does not add any additional semantics about the parameter, so it relies on the schema. Since coverage is complete, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: generating the next available estimate number for a location. It uses a specific verb (generate) and resource (estimate number), and distinguishes it from estimate creation by noting it's a prerequisite for accounts that require an estimateNumber. This is unambiguous and differentiates it from sibling tools like ghl_create_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Some accounts require an estimateNumber when creating an estimate — call this first.' This tells the agent when to invoke it (before creating an estimate) and under what condition (accounts that require it). It doesn't explicitly state when not to use it or alternatives, but the instruction is clear enough for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful filtering and date-format context, but does not disclose pagination behavior, inclusive date semantics, or return shape; given the annotations, 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main action and scope are front-loaded, and the date-format sentence is necessary and placed second.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool, the description plus schema provides enough to invoke it correctly: location scope, optional form filter, date range filter, date format, and pagination defaults. Missing response-shape details are not blockers for calling the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by framing formId and startAt/endAt as optional filter dimensions ('optionally filtered to one form or a date range'). It also reinforces the date format. Page and limit lack descriptions, but their names, defaults, and constraints make them self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('submissions for a location's forms'), and adds optional filters. This clearly distinguishes it from sibling tools like ghl_get_survey_submissions, ghl_list_forms, and ghl_list_surveys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the use case: retrieving form submissions for a location, optionally narrowed by form or date range. It does not explicitly name alternatives, but the context is unambiguous and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavior beyond annotations by explaining that the output is a set of definitions scoped to a location, filterable by model, and that returned IDs are meant to be reused in read/write operations on custom field values. It does not mention pagination or limits, but that is a minor gap for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler. The action and resource are front-loaded, followed by the filter guidance and the downstream usage hint. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two parameters, no required inputs, and full schema coverage, the description is nearly complete: it states what is listed, the filtering dimension, and how the returned IDs should be used. It does not describe the output structure or pagination, but the absence of an output schema and the simplicity of a list operation make this a minor omission rather than a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters, including the model enum and locationId default. The description adds only a light interpretation of 'model' ('which fields apply where') and restates 'location', without introducing new parameter-level meaning beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List custom field definitions for a location') and immediately clarifies the model filter scope. It is clearly distinct from the sibling ghl_get_custom_field by being a list operation, and the phrase 'which fields apply where' adds functional differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on using the model parameter ('Filter by model ... to see which fields apply where') and explains the downstream purpose of the return value ('Use the returned ids when reading/writing custom field values on contacts'). It does not explicitly name alternatives like ghl_get_custom_field for single-field lookup, but the list-vs-get distinction is clear enough from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral detail beyond that: location scoping, pagination support, optional search, and the downstream value of returned IDs. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core action and scope, then adds the most important downstream guidance about product IDs. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with four optional parameters, the description covers location, pagination, search, and the purpose of the results. There is no output schema, so a bit more detail about the response shape could help, but the mention of product IDs plus the read-only annotations makes the tool usable without major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%, with search and locationId documented there; limit and offset have no descriptions but their names and defaults make their purpose clear. The description mentions pagination and optional search but does not add meaning beyond what the schema already provides. This is adequate but not a strong compensatory explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('List products') and adds location scoping plus pagination and search. It also clearly connects the tool to downstream use cases (adding prices, building invoices/estimates), which distinguishes it from other product-related tools like get_product or list_product_prices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool and what to do with its results: retrieve product IDs for prices, invoices, and estimates. It does not explicitly exclude alternatives or state when not to use it, but the use case is concrete enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds context beyond annotations: it notes that workflows cannot be created via API, clarifies that the API only lists existing workflows, and indicates the output contains workflow ids for downstream use. This provides useful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the main purpose, and the second provides an important note about creation limitations and a downstream usage tip. No fluff or irrelevant details. The most critical information (the listing action) is front-loaded, and the usage guidance is clearly separated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, no output schema, and annotations covering safety, the description is fairly complete. It specifies the action, scope, a limitation (can't create via API), and downstream usage. It doesn't describe the response structure in detail (e.g., whether all workflows are returned or paginated), but given the simplicity and the mention of 'returned workflow ids,' an agent can reasonably infer the output shape. The main missing piece is response format, but it's not critical for correctness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, locationId, with a description that covers its meaning (GHL Location ID, defaults to GHL_LOCATION_ID). Schema description coverage is 100%, so the description does not need to add parameter details. The tool description mentions 'in a location,' which aligns with the schema. It adds no extra meaning beyond what the schema provides, so it meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List the automation workflows configured in a location.' It is specific about the resource (automation workflows) and scope (location). It also distinguishes from related siblings like ghl_add_contact_to_workflow by mentioning the returned workflow ids are used with that tool, clarifying that this tool is for listing, not triggering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage directive: 'Use the returned workflow ids with ghl_add_contact_to_workflow to trigger automations.' This tells the agent when and how to use the output. It also implies this tool is read-only (workflows must be built in UI, API cannot create them), which helps avoid misuse. However, it does not explicitly state when not to use this tool relative to other list tools, but given the specific resource, it's implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=false, so mutation is expected. The description usefully adds that GHL fetches and hosts the URL content, which explains the upload mechanism. However, it does not disclose failure behavior, supported file types, or side effects beyond adding the file, so it adds only moderate behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary filler. The action and key constraint are front-loaded, and both the use-case guidance and the exclusion for binary uploads earn their place. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with only three parameters and no output schema, and the description covers the key prerequisite (public URL) and the main alternative (UI for binary uploads). It does not describe the returned representation or what happens after upload, but for this low-complexity tool the description is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the meaning of fileUrl ('publicly reachable URL') but adds no new semantic detail about name or locationId beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Add a file to the Media Library by referencing a publicly reachable URL.' It also clarifies the mechanism ('GHL fetches and hosts it') and explicitly distinguishes this from raw binary uploads. This makes the tool's purpose unmistakable and separates it from sibling media tools like list_media and delete_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete use cases ('deliverables or talent photos already available at a link') and an explicit exclusion: 'For raw binary uploads use the GHL UI.' This clearly tells an agent when to use this tool and when not to, including a named alternative pathway.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior; the description adds meaningful context by stating that voiding 'cancels the invoice while keeping the record.' There is no contradiction with the annotations, and the description provides value beyond the flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the action, followed by the scoping condition and the behavioral outcome. Each sentence earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the description provides the operation, when to use it, and the resulting state. The destructive behavior is already covered by annotations, so the description is adequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents locationId but leaves invoiceId without a description, and the description does not explain invoiceId or locationId further. 'Void an invoice' makes it clear that invoiceId identifies the invoice, but at 50% schema coverage the description only partially compensates for the missing parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Void an invoice') and explains the mechanism: 'Voiding cancels the invoice while keeping the record.' It also distinguishes voiding from deletion, noting this is for invoices that 'can no longer be deleted,' which differentiates it from the sibling delete tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit condition for use: 'invoices that have already been sent.' This clearly communicates when voiding applies and implies that deletion is for unsent invoices, though it does not explicitly name ghl_delete_invoice as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and partial results. The description adds the scoping requirement and clarifies that startTime/endTime are in epoch milliseconds, which are behavioral constraints not present in annotations. It doesn't mention pagination or sorting, but the added context is valuable enough to earn a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first states purpose, the second covers the key precondition and time units. Information is front-loaded, and every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core requirements (list events, time window, scoping) but leaves ambiguity about whether 'one of' means exactly one or at least one of the scope parameters, and whether they are mutually exclusive. It also doesn't address pagination or result limits, which is relevant given the openWorldHint. For a read-only list tool with 6 parameters and no output schema, this is a noticeable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only startTime, endTime, locationId have descriptions). The description compensates for the three undocumented scope parameters (calendarId, userId, groupId) by explaining that one must be provided and their role. It also reiterates the time unit for startTime/endTime, adding clarity. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List) and resource (calendar events/appointments), and scopes it within a time window. It clearly differentiates from siblings like ghl_get_calendars (which lists calendars) and ghl_get_appointment (which retrieves a single appointment). The inclusion of the scoping requirement adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance by stating that one of calendarId, userId, or groupId is required to scope the query, which is a critical prerequisite. It doesn't explicitly compare to alternatives, but the purpose is distinct enough that an agent can infer when to use it. It lacks explicit 'when not to use' guidance, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds behavioral transparency by revealing that line items and amounts are included in the response, which is useful beyond the schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no filler. It front-loads the action and resource, then adds the key response detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-order fetch with readOnlyHint=true, no output schema, and only two parameters, the description is complete enough. It tells the agent what the tool does, how it selects the order, and what kind of data is returned. No additional behavioral or prerequisite context is needed at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage, the description partially compensates: 'by id' clarifies that the required orderId identifies the order to fetch, and 'including line items and amounts' hints at what the id maps to. However, it does not explain the locationId parameter or its defaulting behavior; the schema already covers locationId, so the net added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a specific resource ('single payment order'), and the access method ('by id'), and even previews the response contents ('including line items and amounts'). This clearly distinguishes it from list-style tools like ghl_list_orders and from invoice tools like ghl_get_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: use this when you need one specific payment order by its ID, not when you need multiple orders or need to search. It does not explicitly name alternative tools or exclusions, but the 'single...by id' phrasing provides sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation, and openWorldHint=true. The description adds behavioral context by mentioning pagination and optional filters by status or contact, plus the purpose of reviewing purchase and payment status. It does not contradict the annotations and provides useful additional behavior beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the core action and resource, then adding the use case. Every phrase adds value—pagination, filters, and intent—with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations (read-only, open world) and the schema with defaulting locationId, the description provides enough for an agent to call correctly: it knows this is a paginated list with optional filters against orders. No output schema exists, but return value explanation is not required when absent. The tool is simple enough that no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, with limit, offset, and contactId lacking descriptions. The description partially compensates by indicating 'pagination' (mapping to limit/offset) and 'filter by status or contact' (mapping to status and contactId). It does not explain the default locationId behavior, though that is covered in the schema. This adds meaning but not complete parameter-level detail, giving a baseline-adjusted score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'payment orders' and scope 'for a location'. It distinguishes itself from sibling tools like ghl_get_order (single order) and ghl_list_transactions by focusing on orders. Optional filters are mentioned, making the primary action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool should be used 'to see what was purchased and whether it was paid,' providing a clear context for when to invoke it. It does not explicitly name alternative tools for other order-related queries, such as ghl_get_order for a single order or ghl_list_transactions for transactions, so there are no exclusions. This is clear context without explicit when-not guidance, aligning with a score of 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds key behavior beyond annotations: 'Only provided fields are changed' clarifies partial-update semantics. Annotations indicate idempotent and non-read-only, but the description supplies the important nuance that unspecified fields remain untouched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and resource, with the partial-update rule immediately after. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for basic updates but missing mention of pipelineId and any return value (no output schema). Does not address error conditions or prerequisites beyond required opportunityId, which is schema-covered. Slightly incomplete for a 7-parameter mutation tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description maps common concepts (stage, status, value, name, owner) to schema parameters, covering most fields. However, it omits pipelineId (changing pipeline) despite schema coverage being only 14%. Still compensates well for low schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool's purpose: updating an opportunity, listing specific mutable aspects (stage, status, value, name, owner). Distinguishes from siblings like create_opportunity and get_opportunity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes that only provided fields are changed, indicating a partial-update use case. Does not explicitly mention when to prefer this over create or get, but the update context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (write operation) and idempotentHint=false (may create duplicates), which the description aligns with by stating 'Schedule or publish'. The description adds useful behavioral context: the scheduleDate behavior (omit for draft) and that mediaUrls must already be hosted in GHL. However, it doesn't disclose what happens on validation failure (e.g., invalid accountIds) or whether scheduling requires future dates only. The openWorldHint=true suggests the API may have side effects not fully enumerated, a subtle discrepancy not contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero redundancy. Front-loads the core action, then clarifies scheduleDate and mediaUrls in the second sentence. Efficient use of words – each phrase adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, 2 required, no output schema, and write semantics. The description covers the key scheduling/drafting logic and media prerequisites. However, it doesn't explain the status parameter's full interaction (e.g., what happens when status='published' with no scheduleDate – immediate publish?), nor does it mention account lookups or validation behavior. An agent might need to infer that status='scheduled' requires scheduleDate, and status='published' publishes immediately. The schema provides the enum but not the semantic rules. The description could be more complete here but isn't critically deficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83% (5 of 6 properties have descriptions), so the description adds marginal value. However, it clarifies the critical semantics of scheduleDate ('ISO 8601 time to publish. Omit to create as draft.') which is slightly different from the schema's 'Omit to create as draft.' The description also clarifies that mediaUrls must already be hosted, adding context beyond the schema's 'URLs of media to attach.' The status parameter's interaction with scheduleDate is implied but not fully explained in the description. Given the high schema coverage, the description adds meaningful but not essential clarifications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Schedule or publish a social post to one or more connected accounts') with a specific verb and resource. It differentiates from siblings like ghl_list_social_posts, ghl_get_social_post, and ghl_delete_social_post by focusing on creation/scheduling. The distinction between scheduling and immediate publishing is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use scheduleDate (for scheduled posts) and mentions that omitting scheduleDate creates a draft based on status. However, it does not explicitly state when NOT to use this tool versus alternatives like ghl_list_social_posts or ghl_upload_media_by_url. It also doesn't mention prerequisites like needing connected accounts or how to find accountIds (though ghl_list_social_accounts exists as a sibling).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces with 'cannot be undone.' It adds genuine value beyond annotations by disclosing the draft-only state constraint, which is critical behavioral knowledge an agent needs to avoid failed calls. Minor gap: it doesn't state what happens when invoked on a non-draft invoice (error vs silent no-op).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero wasted words. The core verb+resource is front-loaded, the critical draft-state constraint follows immediately, and the destructive warning closes. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter destructive tool with strong annotations, this is nearly complete. It covers the safety profile (destructive, irreversible), the state constraint (draft-only), and the routing to the correct sibling. It could optionally describe the response/return behavior, but nothing an agent critically needs to avoid misuse is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: locationId is well-documented, but invoiceId is a bare string with no description. The tool description mentions 'invoice' and 'draft' context, which lets an agent infer invoiceId's purpose, but it doesn't explicitly compensate for the undocumented parameter. Adequate but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource pair ('Delete an invoice') and immediately distinguishes itself from the sibling tool ghl_void_invoice by scoping deletion to draft invoices only. An agent can tell exactly what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the condition for use ('Only works while it is a draft') and names the alternative with its routing condition ('a sent invoice must be voided with ghl_void_invoice instead'). This is textbook when-to-use vs when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive and readOnly, but the description adds that the operation 'cannot be undone' and explicitly warns it covers blocked time slots. This reinforces the irreversible behavior and broadens the tool's scope beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences front-load the action and resource, then immediately address scope and the safer alternative. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive operation with no output schema, the description plus annotations cover the necessary selection criteria, safety profile, and parameter meaning. The alternative route is included, so an agent has everything to decide correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers the single parameter at 100%, and the description adds no new syntax or format details beyond restating that it uses an id and accepts blocked-slot ids, which the schema description already mentions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Delete'), resource ('calendar event'), and key scope ('Works for both appointments and blocked time slots'). It clearly distinguishes itself from ghl_update_appointment via the alternative path, making it unmistakable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a when-not-to-use: 'to keep the record but mark it off, use ghl_update_appointment with appointmentStatus "cancelled" instead.' Also clarifies its applicability to both appointments and blocked time slots, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, non-idempotent operation, and the description's 'outbound' phrasing aligns with readOnlyHint=false. The description adds the prerequisite of a valid contact channel and clarifies which body fields are mandatory per channel. It doesn't contradict annotations and provides useful constraints beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences front-load the core action, then cover channel-specific requirements and the contact precondition. Every sentence earns its place; no filler or duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with conditional fields and no output schema, the description covers the essential invocation logic and preconditions. It is slightly incomplete in not describing the response shape or what happens if the contact's channel is invalid, but annotations and schema fill the remaining gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds the cross-field rule that Email requires subject plus either html or message, and SMS requires message. This conditional requirement isn't fully expressed in the schema's required array, so the description materially helps the agent assemble valid parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action, 'Send an outbound message to a contact via SMS or Email,' identifying the verb, resource, and channels. This clearly distinguishes it from sibling read tools like ghl_get_messages and from resource-specific senders like ghl_send_invoice or ghl_send_estimate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete invocation guidance by channel: Email requires subject and html (or message), SMS requires message. It also states a precondition, 'The contact must have a valid phone/email for the chosen channel.' It doesn't explicitly name alternatives, but the context is clear enough for an agent to know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing two crucial behaviors: the items array fully replaces prior items, and only explicitly provided top-level fields are changed. This adds significant clarity about partial-update semantics and the destructive-ish replacement behavior for items, which annotations alone would not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences deliver the essential information with no filler. The core purpose is front-loaded, followed immediately by the two behavioral rules that matter most for correct invocation: item replacement and partial top-level updates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with 8 parameters and no output schema, the description covers the behavior that would otherwise be ambiguous: how items are handled and how partial updates work. It does not describe the return value or any special validation rules, but the required estimateId and optional fields are clear from the schema, so the description is sufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%, so the description carries meaningful weight here. It explains the most complex parameter, items, by specifying replacement behavior, and it clarifies that omitted top-level fields remain unchanged. It does not document date/currency formats, but the parameter names are largely self-explanatory and the general update rule adds real semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing estimate, distinguishing it from creating, deleting, or sending estimates. It also adds the key semantic that items replace prior items, making the operational purpose unmistakable even among the many sibling estimate-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this for an existing estimate, and pass the full set of desired items for replacement. It does not explicitly name alternatives like create_estimate or delete_estimate, but the 'existing estimate' wording effectively implies the correct use case without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

[![gohighlevel-mcp MCP server](https://glama.ai/mcp/servers/vmproductions631-tech/gohighlevel-mcp/badges/card.svg)](https://glama.ai/mcp/servers/vmproductions631-tech/gohighlevel-mcp)

Score Badge

Copy to your README.md:

[![gohighlevel-mcp MCP server](https://glama.ai/mcp/servers/vmproductions631-tech/gohighlevel-mcp/badges/score.svg)](https://glama.ai/mcp/servers/vmproductions631-tech/gohighlevel-mcp)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vmproductions631-tech/gohighlevel-mcp'

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