GHL MCP Server

Server Quality Checklist

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

Latest release: v1.0.1
Disambiguation5/5
Every tool targets a distinct resource and action (e.g., contacts, invoices, calendars, messages), with clear names like ghl_create_contact_note vs ghl_get_contact_tasks. No two tools appear to overlap in purpose.
Naming Consistency5/5
All tools use a uniform ghl_ prefix followed by a predictable verb_noun pattern (list_*, get_*, create_*, update_*, delete_*, search_*, add_*, remove_*, send_*). This consistency holds across all 64 tools without exceptions.
Tool Count2/5
64 tools is far above the typical range for an MCP server, and the calibration indicates 50+ is an extreme mismatch. While each tool maps to a distinct GHL feature and the platform is broad, this volume will likely overwhelm agents and increases selection complexity.
Completeness3/5
Core domains like contacts, opportunities, conversations, and calendar events have solid CRUD coverage, but many resources (forms, surveys, campaigns, funnels, products, blogs, links) are read-only, and operations like invoice updates or social post deletion are missing. Notable gaps exist across the surface.
Average 3.5/5 across 59 of 64 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits 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
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds no behavioral context beyond a list of filter categories, and it includes 'monetary value' which is misleading since no such filter exists. It does not disclose pagination behavior, return structure, or other operational traits, even though the schema includes startAfter/startAfterId and limit.
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 no redundant words. It is front-loaded with the main action 'Search opportunities' and lists filter dimensions compactly. However, it earns a 4 rather than 5 because the misleading 'monetary value' creates unnecessary noise for a tool that otherwise could be a clean one-liner.
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 search tool with 9 optional parameters and no output schema, the description is too sparse. It does not explain how filters combine, what the query parameter does, pagination via startAfter/startAfterId, or the default limit. The unsubstantiated 'monetary value' further reduces reliability, leaving the agent without enough context to correctly invoke the 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 description vaguely maps 'pipeline, stage, status, contact' to some schema parameters (pipelineId, pipelineStageId, status, contactId) but does not add meaning beyond the schema's own parameter descriptions. It omits mention of query, limit, locationId, and pagination parameters, and introduces a non-existent 'monetary value' filter, failing to compensate for the 56% 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 clearly states that the tool searches opportunities (deals) with filters, using a specific verb and resource. It distinguishes itself from get-style tools (e.g., ghl_get_opportunity) by implying a search over a collection. However, it mentions 'monetary value' which is not supported by any schema parameter, slightly clouding the exact scope.
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 explicit guidance on when to use this tool versus alternatives like ghl_get_opportunity or ghl_search_contacts. The description does not mention exclusions, prerequisites, or preferred contexts. The name implies search usage, but the description carries no comparative direction.
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 provide the safety profile (readOnlyHint=false, destructiveHint=false), but the description adds no extra behavioral context such as side effects, permission requirements, or idempotency concerns. The description is essentially a tautology of the name, offering no information beyond the annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, making it highly concise and easy to parse. However, it is under-specified for a tool with 6 parameters, so while efficient, it lacks necessary detail.
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 minimal description, the tool lacks critical context such as return value, side effects, or when to use it. The description only covers the basic purpose, leaving the agent without enough information to invoke it confidently in a real workflow.
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% (5 of 6 properties have descriptions), which exceeds the 80% threshold, so the baseline is 3. The description itself adds no parameter-level information; it relies entirely on the schema for 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 'Create a task for a contact' uses a specific verb (create) and resource (task) with the target (contact), making the primary function clear. It distinguishes from sibling tools like ghl_update_contact_task because 'create' implies a new task, but it does not explicitly reference alternatives.
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 updating or listing tasks, nor are prerequisites or exclusions mentioned. The description only states the action, leaving the agent to infer usage from the name and title.
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, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. However, the description adds little behavioral context: it says 'for a location' but the schema shows locationId is optional, creating uncertainty about what happens if omitted. No information about pagination, ordering, or return format 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 a single sentence with no unnecessary words, making it concise. However, it is so brief that it sacrifices important details, so it earns a high but not perfect score.
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 sparse annotations, the description should provide more context about return values or the impact of omitting locationId. It is too thin for an agent to understand the full behavior of the tool, especially given the optional parameter.
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 only hints that 'locationId' identifies the location, but does not clarify that the parameter is optional or describe its format. The phrasing 'for a location' misleadingly suggests location is required, conflicting with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get all campaigns for a location' with a specific verb and resource, clearly indicating this is a list operation for campaigns. It distinguishes itself from sibling tools like ghl_list_pipelines or ghl_list_surveys by naming the resource. However, the phrase 'all campaigns' and the optional location parameter create slight ambiguity about the exact scope when locationId is omitted.
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 whenever campaigns are needed, but provides no explicit guidance on when to use this tool versus alternatives. No alternatives or exclusions are mentioned; the tool's purpose is clear but contextual usage is only implied by the domain.
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 the tool as read-only, idempotent, and non-destructive. The description adds the location scoping but does not disclose pagination behavior, default limits, or whether locationId is required, which would be useful given openWorldHint.
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 core action. It is efficient, though slightly more detail would improve usefulness without becoming verbose.
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 sparse description, the tool lacks context about return values, pagination, and how it differs from allied tools. The annotations mitigate safety concerns but do not fill the information gap about expected 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?
The schema has 0% description coverage for parameters. The description only hints at locationId through 'for a location' and does not clarify pagination parameters (limit/offset) or requiredness. It fails to compensate for the schema's lack of descriptive 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 clearly states the tool retrieves payment orders for a location, with a specific resource and scope. It is distinct from the singular ghl_get_order, though it does not explicitly mention alternatives or contrast with similar 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. There is no mention of when to use this tool versus alternatives like ghl_list_transactions or ghl_get_order, nor any prerequisites 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 declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the scope of 'scheduled and published' posts, which provides context beyond the annotations. However, it does not disclose pagination behavior or any filtering nuances, so the transparency 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 concise sentence that directly states the tool's purpose with no unnecessary words. It is front-loaded and easy to parse. 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 is relatively simple with two optional parameters and no output schema, but the description does not explain parameter roles or return values. The annotations help with safety, but the agent lacks crucial invocation details such as whether locationId is required or how to handle large result sets. The description is minimally complete for a simple list operation but has clear gaps.
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?
The input schema has two parameters (limit and locationId) with zero description coverage. The description does not mention either parameter, leaving their meaning and usage entirely unexplained. An agent would have to guess that limit controls pagination and locationId filters by location, but there is no textual support. 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 tool retrieves social media posts, specifically those scheduled and published. It uses a clear verb ('Get') and a specific resource ('social media posts'), which distinguishes it from sibling tools like ghl_create_social_post and ghl_list_social_accounts. However, it does not explicitly contrast itself with other list tools, but the resource is unique enough.
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, such as ghl_list_social_accounts or ghl_create_social_post. The description does not mention exclusions, prerequisites, or typical scenarios. The usage is only implied by the tool name and brief description.
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 write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds location scoping but does not disclose additional behavioral details such as duplicate handling, permission requirements, or the optionality of locationId. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the action, but its brevity borders on under-specification, omitting useful context that could be added without harm.
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 with only two parameters and no output schema, the description provides the core action but lacks essential context: the meaning of locationId, whether it is optional or derived from context, and what the return value is. The openWorldHint annotation suggests potential side effects that are not addressed.
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%, with 'name' documented as 'Tag name' but 'locationId' lacking any description. The tool description adds no parameter semantics and fails to explain what locationId represents or its role in the operation, leaving a significant gap for an undocumented parameter.
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: 'Create a new tag in the location,' which clearly indicates a create operation for a tag resource. It is distinct from sibling tools like ghl_get_location_tags (list) and ghl_add_contact_tags (add existing tags to contacts), but the term 'location' could be more explicitly defined to reduce ambiguity.
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 any prerequisites, scenarios, or exclusions, leaving the agent without context on when to invoke this tool over similar tag-related operations like ghl_add_contact_tags.
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 write operation (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds no behavioral context beyond that. It doesn't explain whether updates are partial/full, how omitted fields are handled, or any side effects. The description carries minimal extra value over 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 concise sentence with no wasted words. It states the core purpose efficiently and is appropriately front-loaded with the action verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no output schema, and the description is only 'Update an existing appointment/event.', it is severely incomplete. It provides no information about update semantics, return values, error handling, or which fields are changeable. This is far from adequate for an agent to use the tool correctly.
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?
With schema description coverage at only 11% (only eventId has a description), the description does nothing to compensate for the other 8 parameters. It mentions no parameter names, no enum meanings (like status values), and no field semantics, leaving the schema's self-explanatory property names as the only guidance. This is insufficient for a 9-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') and the resource ('existing appointment/event'), which distinguishes it from sibling tools like create or delete. The verb and resource are 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 usage is implied by the word 'existing' (you update something that already exists) and the verb 'update', but there is no explicit guidance on when to use this tool versus create/delete, nor any prerequisites like the required eventId. This is implied rather than stated.
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 write operation (readOnlyHint: false). The description adds no additional behavioral context beyond that—no mention of side effects, idempotency, return values, or required permissions. It does not contradict annotations, but provides no extra value.
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 wasted words. It is front-loaded and easy to scan.
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 no output schema, this description is incomplete. It does not mention what the operation returns (e.g., calendar ID, booking page URL) or any required context like locationId. Given 5 parameters and moderate complexity, more detail is necessary.
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 does not elaborate on any parameter meaning. Schema description coverage is only 40%, with three params (locationId, description, calendarType) lacking descriptions. Since the description fails to compensate for this gap, parameter semantics remain poorly communicated.
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 ('Create') and resource ('a new calendar in GoHighLevel'), distinguishing it from sibling tools like listing or getting calendars. It 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 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_create_event or ghl_update_calendar. The description simply states what it does without mentioning prerequisites, like needing a locationId, 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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds no extra behavioral context such as return format, rate limits, auth requirements, or behavior when the calendar ID is invalid. It is neutral but uninformative 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?
The description is a single, concise sentence that directly states the tool's function without unnecessary words. It 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and annotations, but there is no output schema. The description does not explain what 'details' include or what to expect in the response, nor does it indicate any caveats. It is minimally viable but lacks contextual richness for a get 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?
Schema description coverage is 100%, with calendarId described as 'Calendar ID'. The tool description adds no additional meaning about the parameter, but the schema already provides sufficient semantic coverage, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific calendar' uses a specific verb ('Get') and resource ('specific calendar'), clearly indicating it fetches one calendar rather than listing them. It distinguishes from sibling ghl_list_calendars by emphasizing 'specific', though it does not explicitly mention using the calendarId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like ghl_list_calendars. It does not state prerequisites, exclusions, or scenarios where the list variant would be preferred. The description offers no usage context beyond the basic 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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds only 'in a location', which is redundant with the locationId parameter, and doesn't disclose pagination, response format, or other behaviors. 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, concise sentence with no fluff. It front-loads the action and is appropriately sized for a simple list/get tool.
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?
Despite rich annotations, the description lacks essential contextual details such as whether locationId is required, how pagination works, and what a 'submission' entails. With no output schema, the description should provide more context but doesn't.
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 formId has a description). The tool description doesn't explain limit or locationId semantics beyond the schema, and its mention of 'a location' doesn't clarify whether locationId is required or how limit operates. It fails to compensate 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 clearly states the tool retrieves form submissions for a location, using the specific verb 'Get' and resource 'form submissions'. It distinguishes itself from sibling tools like ghl_list_forms, which lists forms, and other entity-specific 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 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 doesn't mention any prerequisites, exclusions, or direct comparison with sibling tools, leaving the agent to infer usage from the 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about the types of accounts (Facebook, Instagram, Google) but does not disclose additional behavioral traits such as pagination, response format, or any quirks. 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 a single, well-structured sentence that is front-loaded with the core purpose. It contains no unnecessary words and is appropriately sized for a simple list operation.
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 is simple, but the description lacks essential context such as the meaning of locationId, whether the response is paginated, and any special behaviors hinted by openWorldHint. With no output schema to clarify return shape, the description should provide more detail to fully inform the agent.
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?
The input schema has one optional parameter (locationId) with no description, and the description does not mention it at all. With 0% schema description coverage, the description fails to compensate, leaving the parameter's purpose and usage completely 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 tool's purpose with a specific verb ('Get') and resource ('all connected social media accounts'), listing examples that help distinguish it from sibling tools like ghl_list_social_posts. This makes the tool's identity 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, no exclusions, and no mention of prerequisites or filters. While the description implies it is for retrieving social media accounts, it does not explain when to choose 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false), non-idempotent, and open-world. The description adds no behavioral context beyond the obvious action—no mention of side effects, return values, or permissions. Given the presence of annotations, this misses an opportunity to enrich transparency.
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, front-loaded with the verb, no redundant details. It is efficiently sized for the core purpose, and every word adds value. This is an exemplary model of conciseness.
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?
Despite having 10 parameters and no output schema, the description is only a single sentence. It does not mention that the tool returns the created opportunity, nor any relationships between required parameters (e.g., pipelineStageId must belong to pipelineId). It is inadequate for a robust write operation with rich 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 around 70-80%, with most parameters having meaningful descriptions. The tool description itself does not elaborate on any parameter, so it adds little beyond what the schema already provides. Baseline 3 is appropriate because the schema carries most of the parameter 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?
The description 'Create a new opportunity/deal in a pipeline' uses a specific verb and resource, and the pipeline context distinguishes it from sibling tools like ghl_update_opportunity, ghl_get_opportunity, and ghl_delete_opportunity. It clearly states what the tool accomplishes.
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, nor does it mention prerequisites such as needing pipelineId and contactId from other tools (e.g., ghl_list_pipelines, ghl_search_contacts). It is a bare statement of function without contextual usage advice.
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 tool as read-only, idempotent, and non-destructive, so the description does not need to re-state safety. It adds context about location-based retrieval and filtering, but does not disclose pagination, return format, or the fact that 'date range' filtering is unsupported by the schema. The false date range claim is a behavioral misrepresentation that the annotations do not cover, preventing a higher score.
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 main purpose ('Get invoices for a location') and then lists filters. Every word earns its place, though the unwarranted 'date range' mention is a small waste and should be removed or corrected to match the actual schema.
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 gives the core purpose and some filter options, but with no output schema and 4 parameters, it is incomplete. It does not explain what fields are returned, how pagination works via 'limit', or that 'locationId' is essential (implied but not stated). Given the tool's simplicity and strong annotations, a score of 3 reflects the absence of these practical details.
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 0% schema description coverage, the description must compensate by explaining parameters. It explains 'status' and 'contact' (likely mapping to the 'status' and 'contactId' properties), but omits 'limit' entirely and incorrectly introduces a 'date range' filter that has no corresponding schema property. This partial coverage plus a misleading addition leaves significant gaps for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves invoices for a location and supports filtering by status, contact, or date range. It distinguishes itself from the singular 'ghl_get_invoice' sibling because it is a plural list operation, though it does not explicitly reference that alternative. However, the mention of 'date range' filtering is misleading because the schema contains no date parameters, which slightly detracts from clarity.
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 used to list invoices for a location, with optional filters. It does not explicitly state when to prefer this over 'ghl_get_invoice' for a single invoice, nor does it provide exclusions or prerequisites. The context is reasonably clear but lacks guidance on alternatives 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and negligible destructiveness. The description adds the location-scoping context, which is useful, but does not disclose pagination behavior, response format, or any other operational details 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?
The description is a single, front-loaded sentence with no unnecessary words. It directly states the action and object, matching the title and making efficient use of space.
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 strong annotations and no output schema, the description is adequate. It covers the core action and scope, but could clarify what happens when locationId is omitted, though the low complexity makes this a minor gap.
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 0% for the single locationId parameter, so the description must compensate. It does not mention locationId at all, nor its optionality, format, or behavior when omitted, leaving the parameter meaning entirely 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 uses the specific verb 'Get' with resource 'all calendars' and location scope, clearly conveying a list operation. It distinguishes from siblings like ghl_get_calendar (singular) and ghl_create_calendar by stating 'all calendars'.
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_get_calendar or ghl_create_calendar. The purpose is implied but not explicitly differentiated, and there are no exclusions or conditional recommendations.
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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context (location scoping) but does not disclose pagination, ordering, or return format. With annotations covering the risk profile, a 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?
The description is a single, clear sentence with no filler or redundancy. It effectively front-loads the core information: the operation and the target resource.
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 3 parameters and strong annotations, the description gives a minimal viable overview. However, it omits details like pagination behavior, whether locationId is required, and what fields are returned. Since there is no output schema, a bit more context would be helpful, so 3 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 0%, but the description adds meaning to locationId by indicating transactions are scoped by location. It does not explain limit or offset, though those are common pagination parameters with defaults and bounds already in the schema. The description partially compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('payment transactions') and the context ('for a location'), using a specific verb 'Get'. It is distinct from sibling tools like ghl_list_invoices and ghl_list_orders, though it does not explicitly contrast with them.
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 such as listing invoices or orders, nor any mention of prerequisites like requiring a locationId. The description only states what the tool does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the 'in a location' scoping, which hints that locationId may be important, but it does not disclose other behavioral traits such as pagination, return format, or how missing locationId behaves. Since the annotations carry the primary safety disclosure, a score of 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?
The description is a single concise sentence with no redundant words. It is fully front-loaded and immediately communicates the core function. There is no wasted verbiage, making it highly scannable for an AI agent.
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 a simple two-parameter schema but no output schema. The description is too minimal to convey key details like the return payload, whether querying is fuzzy or exact, or the implications of omitting locationId. Without any additional context, the description is insufficient for a complete understanding of the tool's 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 50%, with only 'query' described (search by name or email). The description does not clarify the meaning or semantics of 'locationId' beyond the vague 'in a location' phrase. It fails to compensate for the missing schema description, leaving the agent uncertain about the locationId parameter's format, requiredness, or behavior.
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: searching for users/team members. This directly distinguishes it from sibling search tools like ghl_search_contacts or ghl_search_opportunities by specifying the resource type. The phrase 'in a location' adds a scope that further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are no explicit usage scenarios, prerequisites, or exclusions. The agent is left to infer that this tool is for finding users, but no context is given about when to prefer it over other search tools or what specific use cases it addresses.
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 destructiveHint=true and idempotentHint=true. The description adds no further behavioral context such as irreversibility, impact on payments, or required permissions. It merely restates the action without disclosing consequences.
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 wasted words; it is concise and front-loaded with the 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 one-parameter mutation, the description covers the basic action but omits preconditions and effects. Given the low complexity and presence of annotations, it is minimally adequate but not rich.
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 invoiceId is not described in the schema (0% coverage). The description implies invoiceId identifies the invoice to void, but provides no details about format, source, or validation. Some meaning is added beyond the raw schema, but it remains minimal.
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 'Void' and resource 'existing invoice', distinguishing it from sibling tools like ghl_create_invoice, ghl_get_invoice, and ghl_send_invoice.
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 vs alternatives, nor any prerequisites or conditions such as invoice state or permissions. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 is consistent. However, it adds no extra behavioral context such as whether the cancellation is soft or hard, whether attendees are notified, or any irreversible side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct phrase that directly states the action, with no filler words. It could arguably be more informative but 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?
Given the simple 1-parameter tool and existing annotations, the description is minimally sufficient but could benefit from clarifying what 'cancel' means versus a hard delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already describes eventId as 'Event ID to delete' with 100% coverage. The description adds no additional parameter 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 clearly states the tool deletes/cancels an appointment, using a specific verb and resource. It distinguishes from sibling tools like ghl_create_event, ghl_update_event, and ghl_get_events.
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, such as when to cancel versus update an event, nor 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. However, the description adds no extra behavioral context such as ordering, pagination, or whether deleted notes are excluded.
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 that directly conveys the tool's purpose with no unnecessary words 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 simple get-by-contact tool with one parameter and no output schema, the description is mostly adequate. It could mention what notes are returned (e.g., format, ordering), but given the simplicity, it 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?
The schema fully documents the only parameter, contactId, with a description. The description adds no additional parameter semantics, 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 clearly states the operation: 'Get all notes for a contact.' It uses a specific verb and resource, and distinctly separates this from sibling tools like create/delete note and get_contact_tasks.
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. The description does not mention alternatives, exclusions, or prerequisites, leaving the choice solely to 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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds no behavioral context such as pagination, sorting, or response format, only restating the operation.
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?
Single sentence, front-loaded, and zero waste. Perfectly 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?
For a simple list tool with no output schema, the description is adequate but does not describe return structure, pagination, or parameter details. Annotations cover safety, but overall guidance is thin.
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 has one parameter (locationId) with no description (0% coverage). The description mentions 'for a location' which helps map the parameter, but does not explain format, optionality, or defaults. Minimal compensation for the schema 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?
Description uses specific verb 'Get', resource 'blogs', and scope 'for a location', clearly distinguishing it from sibling list tools. It is not a tautology and fully communicates 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: use when you need all blogs for a location. No explicit alternatives or exclusions are provided, but the resource is unique among siblings, so the guidance is adequate but not elaborated.
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 adds 'all' and 'for a location' which clarify scope but does not disclose pagination, ordering, or response format. Since annotations already declare readOnlyHint=true and destructiveHint=false, the safety profile is covered, but the description adds limited behavioral detail 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?
The description is a single concise sentence that front-loads the purpose and scope. Every word earns its place, with no redundant 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?
For a simple read-only list tool with strong annotations, the description provides the essential 'what' and 'for what'. It does not detail return structure, but given the low complexity and absence of an output schema, the coverage is adequate for an agent to infer the tool's 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?
The schema has one parameter (locationId) with no description and not marked as required. The description mentions 'for a location' but does not clarify whether locationId is mandatory, what format it should take, or what happens if omitted. With 0% schema description coverage, the description should compensate but does not sufficiently.
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 ('Get all') and the resource ('funnels/websites') for a specific scope ('for a location'). It effectively distinguishes the resource type from sibling list tools, though it does not explicitly differentiate usage from 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?
Usage is implied: use this tool to retrieve all funnels/websites for a given location. However, there is no explicit guidance on when to prefer it over alternatives, what to do if no locationId is provided, or any 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 a non-read-only, non-destructive, non-idempotent operation. The description adds the 'via email' detail, which aligns with openWorldHint. However, it does not disclose side effects like marking the invoice as sent or whether repeated calls send duplicate emails.
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 directly states the purpose, with no unnecessary words or 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 simple one-parameter send action, the description is minimally sufficient but lacks important context such as the need for the invoice to exist or the contact's email being available. Given the simplicity, it's acceptable but not enriched.
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 0% schema description coverage, the description must compensate, but it does not. It only implies that invoiceId identifies the invoice to send, which is already evident from the parameter name. No additional context is given on how to obtain the ID or any 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 clearly states the specific action: sending an invoice via email. It distinguishes from sibling tools like ghl_create_invoice (create vs send) and ghl_get_invoice (retrieve).
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, prerequisites (e.g., invoice must exist), or how it relates to ghl_create_invoice or ghl_void_invoice. The description simply states the action without any contextual direction.
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 adds no behavioral context beyond what the annotations already provide. Annotations already declare destructiveHint=true and readOnlyHint=false, and the description simply restates the 'delete' action without noting permanence, side effects, or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words or repetition. It is appropriately 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 required params, no output schema) and the presence of annotations covering safety, the description is minimally adequate. However, it lacks any contextual hints about prerequisites, return behavior, or when to prefer this tool over other note-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (contactId and noteId) explicitly described. The description adds no additional meaning to the parameters, 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 clearly states the action ('Delete'), the resource ('a specific note'), and the context ('from a contact'). It is specific and distinct from sibling tools like ghl_create_contact_note and ghl_get_contact_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to delete a contact note), but it does not explicitly mention alternatives or exclusions. No guidance is given on how this differs from other contact note operations.
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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral details such as pagination, ordering, or inclusion of completed tasks, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant words. It is slightly redundant with the title but still communicates the scope clearly, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and no output schema, the description is sufficient. It does not explain return format or edge cases, but annotations and schema cover the essential operational 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 fully documents the only parameter, contactId, with 100% coverage. The description adds no additional meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with resource 'tasks' and scope 'for a contact', unambiguously identifying the operation. It distinguishes itself from sibling tools focused on notes, conversations, or other 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 like ghl_get_contact_notes or ghl_create_contact_task. It does not mention any prerequisites, exclusions, or context where this should be preferred.
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 a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds the location scoping constraint, but does not disclose any additional behavioral traits such as what 'all' means in light of the openWorldHint, whether pagination is involved, or what happens when locationId is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no wasted words. It is highly concise and well-structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema) and rich annotations, the description is adequate but lacks some contextual depth. It does not clarify the return format, the meaning of 'all' in the presence of openWorldHint, or the implications of omitting the optional locationId.
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 description coverage at 0%, the description must compensate. It maps locationId to 'for a location', providing a minimal semantic link. However, the parameter name itself already conveys the meaning, so the description adds little beyond what the schema property name suggests.
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 ('Get all') with a clear resource ('trigger links') and context ('for a location'). This clearly distinguishes it from sibling list tools such as ghl_list_pipelines or ghl_list_surveys, which target different resource types.
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 other list tools, nor any prerequisites or contextual clues beyond the location scope. It fails to mention alternatives or exclusions, leaving the agent to infer usage solely from the resource name.
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 mutating, non-destructive, idempotent operation, and the description aligns by stating 'Remove'. However, it adds no extra behavioral context—such as side effects on the contact, why removal might fail, or whether it is reversible. Given the annotations, the description meets a minimal bar but does not enrich understanding.
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 directly states the action and object. It is front-loaded and contains no filler, making it efficient for an agent 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 two-parameter mutation with no output schema, the description is functionally adequate. However, it lacks details about expected response, error conditions, or any workflow-specific nuances. The agent can perform the call but may not know what to expect afterward. This is a clear 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 descriptions fully cover both parameters (contactId and workflowId), so the description does not need to repeat them. The tool description itself adds no additional parameter-level meaning, and the schema already provides sufficient clarity. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') with a clear resource ('contact from a GHL workflow'), making its purpose unambiguous. It is distinct from sibling tools like ghl_add_contact_to_workflow, so there is no confusion.
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 or when alternatives might be preferred. It does not mention prerequisites (e.g., contact must be in the workflow) or contrast with related tools such as ghl_add_contact_to_workflow. The usage context is only implied by the name.
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, destructiveHint=false, and idempotentHint=true, which provide a basic safety profile. The description adds no extra behavioral details such as effects on non-existent tags, authentication needs, or return format. It neither contradicts annotations nor adds significant transparency.
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 directly conveys the operation without any redundant words. It is concise, front-loaded, and contains 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 tool is simple with two well-described parameters and good annotations, but there is no output schema and the description does not mention return values or edge cases (e.g., removing non-existing tags). The openWorldHint suggests possible unknown side effects, which the description does not address. This is a clear gap for a mutation 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 provides descriptions for both parameters (contactId and tags) with 100% coverage. The description does not add any additional meaning to the parameters, 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 'Remove one or more tags from a contact' uses a specific verb and resource, clearly distinguishing it from sibling tools like ghl_add_contact_tags or ghl_update_contact. It precisely states the action and the object.
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_add_contact_tags or ghl_update_contact. The description only states the action without context on prerequisites, exclusions, or scenarios.
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 readOnly=false, destructive=false, and idempotent=true. The description adds only the word 'existing,' implying the task must already exist, but provides no detail on update semantics, partial update behavior, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded and communicates the core purpose efficiently.
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 tool has 7 parameters, low schema description coverage, and no output schema, this description is insufficient. It lacks context on how updates work, which fields are optional, and what the outcome 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 only 29% (only contactId and taskId have descriptions). The description mentions no parameters, failing to compensate for the low coverage. It adds no meaning for body, title, dueDate, completed, or assignedTo.
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 an existing task for a contact.' This uses a specific verb and resource, distinguishing it from sibling tools like ghl_create_contact_task and ghl_get_contact_tasks.
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?
No explicit guidance is provided about when to use this tool versus alternatives. The purpose is implied, but there are no exclusions or references to create/get task 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=false, idempotentHint=true, and destructiveHint=false, so the agent knows it is a non-destructive write operation. However, the description adds no extra behavioral context such as whether the contact must already exist, side effects on workflow enrollment, or duplicate handling. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Add a contact to a GHL workflow/automation.' Every word earns its place, with no fluff or redundancy. This is exemplary 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?
The tool is simple with only two required parameters and no output schema. Annotations cover idempotency and write semantics, and the schema documents the parameters fully. The description, while minimal, is adequate for this low-complexity operation, though it could benefit from a hint about return behavior or exceptions.
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 provides descriptions for both parameters (contactId as 'Contact ID', workflowId as 'Workflow ID to add contact to'), yielding 100% coverage. The description adds no additional meaning or clarification beyond restating the action, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ("Add") and identifies both the resource (contact) and the target (GHL workflow/automation). It clearly distinguishes itself from the sibling tool ghl_remove_contact_from_workflow, so there is no ambiguity about its function.
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. There is no mention of prerequisites, exclusions, or the contrasting remove tool in the description. The agent must rely entirely on the name and sibling list to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, covering the write and non-idempotent nature. The description adds useful context like 'locationId (uses default if omitted)' and 'Returns: Created contact object with ID', but does not disclose potential side effects like duplicate creation behavior beyond the annotation's idempotentHint.
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 well-structured: a one-sentence purpose, a clear args list, and a return line. Every sentence adds value with no redundancy, maintaining high readability.
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 tool with 18 optional parameters and no output schema, the description provides sufficient context: it identifies key fields, explains customFields structure, notes locationId's default, and states the return value. It lacks mention of prerequisites or limitations, but the annotations and schema cover the safety and parameter surface adequately.
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%, so the schema does not fully document all parameters. The description adds meaningful grouping for basic contact info and explains the customFields format ([{id, field_value}]) and locationId default behavior. However, it omits several schema parameters (e.g., name, city, dnd) and 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 clearly states 'Create a new contact in GoHighLevel' with a specific verb and resource. It distinguishes itself from sibling tools like ghl_update_contact and ghl_upsert_contact by explicitly focusing on 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention ghl_upsert_contact for create-or-update scenarios or ghl_update_contact for modifications, leaving the agent to infer appropriate usage solely from the word 'Create'.
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 destructiveHint=false, so the safety profile is known. The description adds no additional behavioral context such as side effects, return behavior, or authorization needs, but it does not contradict annotations. For a simple create operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler. It is front-loaded and efficiently communicates the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with only 3 scalar parameters and no output schema, the description plus schema cover most needed information. However, it lacks explicit usage guidance and does not mention the optional userId semantics, though these are in the schema. Overall, it is close to complete for this level of simplicity.
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 each parameter (contactId, body, userId) has a description, so the schema carries the semantic weight. The description does not add any extra meaning beyond what the schema already provides, which matches the baseline 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 'Add a note to a contact' clearly states the action (add) and the resource (note) and its target (contact). It distinguishes itself from siblings like ghl_get_contact_notes and ghl_delete_contact_note by implying 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?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. While the purpose is clear, the agent gets no context about when a note should be added vs. a task or tag, or how it relates to ghl_get_contact_notes.
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 operation (readOnlyHint=false), non-destructive, and openWorld. The description adds no additional behavioral context beyond stating the action, so it meets the baseline without enriching 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the core purpose. There is no unnecessary detail or repetition, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the description adequately covers the action. While there is no output schema or detailed side-effect information, the tool's straightforward purpose and informative schema make the description sufficient. It could mention more about prerequisites or return values, but it is not critically incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 73%, which is moderate. The description itself mentions no parameters, but the schema provides descriptions for most fields. Since 27% of parameters lack descriptions (e.g., locationId, appointmentStatus), the description could have compensated but didn't, keeping this at 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 clearly identifies the action ('Create') and the resource ('a new appointment/event on a GHL calendar'), making it easy to understand what the tool does and distinguishing it from siblings like ghl_update_event or ghl_delete_event.
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. While the sibling names suggest related event operations, the description does not explicitly state exclusions or mention when to choose this over update/delete/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 declare destructiveHint=true and readOnlyHint=false. The description aligns with these by saying 'permanently delete,' which adds a small nuance of irreversibility beyond the annotation. However, it does not disclose any additional behaviors like cascading deletions, auth requirements, or rate limits. Minimal added value over 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 wasted words. It front-loads the core action and resource, making it instantly scannable. It is appropriately concise for a simple one-parameter delete 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?
For a simple delete tool with one parameter and clear annotations, the description is reasonably complete. It communicates the essential purpose and irreversible nature. However, it lacks any mention of consequences for the opportunity or prerequisites, such as whether the opportunity must exist. Given the simplicity, it does not need extensive context, but a bit more 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?
The input schema already provides 100% coverage for the single parameter, describing it as 'Opportunity ID to delete.' The description adds no additional semantic meaning beyond this. The baseline of 3 applies since schema coverage is high.
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 'Permanently delete an opportunity' uses a specific verb ('delete') and resource ('opportunity'), clearly distinguishing it from sibling tools like update, create, or get. The word 'permanently' adds crucial nuance about irreversibility, 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?
No guidance is provided on when to use this tool vs alternatives. There is no mention of prerequisites, irreversibility warnings, or that this should be used instead of updating status or deleting via other means. The agent must infer usage from the name and description 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds only the scope ('all tags in a location') and does not disclose potential pagination, response format, or parameter requirements, which would add 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. 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.
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 (1 param, no output schema, strong annotations), the description is nearly complete. It clearly states what is returned (tags) and their scope (location). However, it omits any note about the locationId requirement or potential edge cases, leaving a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (locationId) with 0% description coverage. The description's phrase 'in a location' implies that locationId is the location identifier, but it does not explicitly explain the parameter or mention that it appears required despite not being marked as such. Some meaning is added, but not enough to fully compensate for the missing schema descriptions.
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 ('Get') and resource ('tags') with a clear scope ('in a location'). This clearly distinguishes it from sibling tools like get_location or add/remove 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 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 that this is the read counterpart to create_location_tag or how it differs from get_location. No usage context is given beyond the basic operation.
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, idempotentHint, and non-destructive behavior, so the description does not need to cover safety. It adds some context about return content ('SMS, email, and other message types') but does not disclose pagination, ordering, or default limit behavior. Given the strong annotations, this is adequate but not exceptional.
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 with the verb and resource. Two sentences provide essential information without unnecessary detail. Every word contributes value, and the structure is immediately scannable.
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?
Although the tool is simple and annotations cover safety, the description lacks some contextual details that would improve completeness. Without an output schema, it only vaguely hints at return content ('SMS, email, and other message types') and does not mention pagination, default limit, or that conversationId is required (though schema covers that). For a basic getter with strong annotations, this is minimally complete but leaves room for improvement.
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 67% (conversationId and type are described; limit is not). The description does not add any new parameter semantics beyond what the schema already provides—'SMS, email, and other message types' essentially reiterates the schema's type filter description. The limit parameter remains undocumented in both schema and description, and the description does not clarify how parameters interact.
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: retrieving messages from a conversation thread. It uses a specific verb ('Get') and resource ('messages in a conversation thread'), and distinguishes itself from sibling tools like ghl_get_conversation (which likely retrieves conversation metadata) and ghl_send_message (which sends messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need messages in a conversation) but does not provide explicit guidance on when to use it instead of alternatives like ghl_get_conversation or ghl_search_conversations. No exclusions or alternative tool names are mentioned, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds little beyond 'details', with no extra context about return structure, possible errors, or rate limits. For a simple get operation, 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?
The description is a single, front-loaded sentence with no filler. 'Get details of a specific opportunity/deal.' is compact and directly readable.
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 one required parameter, complete schema documentation, and strong annotations. The description effectively communicates the core function, and while it doesn't detail the return fields (no output schema), it's sufficient for a get-by-ID operation in this 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?
Schema description coverage is 100% for the single parameter 'opportunityId' described as 'Opportunity ID'. The description does not add any additional meaning or format beyond the schema, so it sits at the baseline 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 'Get details of a specific opportunity/deal' clearly identifies the verb (Get), resource (opportunity/deal), and specificity (specific). It distinguishes from sibling tools like ghl_search_opportunities, ghl_create_opportunity, and ghl_update_opportunity by focusing on a single known entity.
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 doesn't mention that this is the tool to use when you have an opportunityId, nor does it point to ghl_search_opportunities for finding opportunities by criteria. There are no exclusions or alternative references.
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, idempotentHint=true, and destructiveHint=false, so safety is clear. However, the description adds no additional behavioral context such as pagination, rate limits, or what happens when locationId is omitted. It only restates the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that gets straight to the point with 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?
While the tool is simple, the description leaves ambiguity about the optional locationId (the schema marks it optional, but the description implies a specific location) and does not describe the return structure. Given no output schema and minimal parameter guidance, the description is only partially 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?
The input schema has one parameter (locationId) with no description, and the semantic coverage is 0%. The description's phrase 'for a location' merely echoes the parameter name and does not clarify whether the parameter is required, its default behavior, or its format. This provides minimal added 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 clearly states a specific verb ('Get'), resource ('products'), and scope ('for a location'). It is distinct from all sibling tools, which deal with other entities like pipelines, surveys, or campaigns.
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 no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The usage is only implied by the resource name, but no context is provided about how this fits with other 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safe read-only nature is covered. The description adds useful behavioral context by specifying 'active' subscriptions and location scoping, but it does not disclose pagination behavior, default limit, or what happens when locationId is omitted.
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 is front-loaded with the verb and resource. It contains no fluff or redundant information, and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with rich annotations, the description provides the core purpose but leaves out important operational details such as pagination via limit, whether locationId is required, and what the response contains. Given the low schema coverage and no output schema, the description is adequate 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%, so the description must compensate. It mentions 'for a location' which loosely maps to locationId, but it does not explain the limit parameter, nor does it clarify whether locationId is required. The schema provides numeric constraints for limit but no semantic meaning, leaving 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 clearly states the action ('Get'), the resource ('subscriptions'), and the scope/qualifier ('active', 'for a location'). It distinguishes this tool from siblings like ghl_list_pipelines and ghl_list_campaigns by specifying subscriptions and the active-status filter.
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 active subscriptions for a location, but it does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or alternative tool references. A clear context is present, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, open-world, and non-destructive, so the description does not need to repeat that. It adds some behavioral context (returns threaded conversations with latest message info) but omits pagination, ordering, or filter combination semantics. Credit is given for the annotation coverage, but the added description is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. Every word adds value, and there is no redundancy. It is an ideal length for a straightforward search 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?
With 5 parameters, no required fields, and no output schema, the description gives the core purpose and partial return info but leaves out important details: the meaning of locationId, the role of limit (pagination), and the exact output shape beyond 'threaded with latest message info'. It is adequate for an agent to understand the basic function, 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 only 40% (query and contactId have descriptions). The description mentions contact ID, query, and status, but merely restates the schema's existing descriptions without adding meaning for those params. It completely ignores limit and locationId, and does not clarify how filters combine or default values. The description fails to compensate 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 clearly identifies the action (search) and resource (conversations), and distinguishes itself from sibling tools by naming specific filter dimensions (contact ID, query, status) and return characteristics (threaded conversations with latest message info). This makes 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?
Usage is implied through the verb 'search' and the listed filters, but there is no explicit guidance on when to choose this tool over alternatives like ghl_get_conversation or ghl_get_messages, nor any exclusions or prerequisites. The context is clear but under-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 declare readOnlyHint=false and idempotentHint=true. The description adds that it updates existing opportunities and lists updateable fields, providing some behavioral context. It does not discuss side effects or permissions, but the annotations cover the basic 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?
The description is a single concise sentence that front-loads the verb and resource. It lists relevant examples without any fluff or redundant content, making it highly efficient.
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 an 8-parameter mutation tool with no output schema, the description is too brief. It does not describe return values, partial update behavior, error handling, or any prerequisites. Although the examples give some direction, the lack of depth leaves significant gaps for an agent.
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 (25%, only opportunityId and pipelineStageId have descriptions). The description partially compensates by mapping examples to parameters ('move stages' → pipelineStageId, 'change value' → monetaryValue, 'update status' → status), but it does not explain the remaining parameters like name, source, assignedTo, or pipelineId.
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 'Update an existing opportunity' with specific examples of what can be changed (stages, value, status). This identifies it as a general update tool. However, it does not explicitly distinguish it from the sibling 'ghl_update_opportunity_status', which also updates status, creating a slight 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 examples 'move stages, change value, update status' provide concrete scenarios for when to use this tool. It does not mention alternatives or exclusion conditions, but the context is clear enough for an agent to infer 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=false, idempotentHint=true, and destructiveHint=false, which cover the operation's safety profile. The description merely restates the action and the status values that are already defined in the input schema enum, adding no new behavioral context such as side effects, prerequisites, or reversibility. With annotations present, the description fails to add 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?
The description is a single, compact sentence that conveys the action and allowed values without any filler or redundancy. It is appropriately sized for the tool's simplicity.
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 with rich annotations and full schema coverage, the description is nearly sufficient. It lacks any mention of return values or error conditions, but the absence of an output schema and the straightforward nature of the operation make the description reasonably complete. The only gap is the lack of explicit guidance on when to choose this over the sibling update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'status' and 'opportunityId' have descriptions in the schema. The tool description does not add any additional meaning or usage details for the parameters beyond what is already present, so it meets the baseline without exceeding it.
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 ('Change') and clearly identifies the resource ('status of an opportunity'). It also enumerates the allowed values (open, won, lost, abandoned), making its scope explicit and distinguishing it from the broader ghl_update_opportunity sibling tool.
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 name and description: it is for updating opportunity status specifically. However, it does not explicitly state when to use this tool versus alternatives like ghl_update_opportunity for other fields, nor does it mention any conditions (e.g., 'use this when only changing status'). This leaves the decision to the agent based on 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:false, so the write nature is known. The description adds that it creates a 'new' field 'for contacts,' which is useful but does not disclose any additional side effects, idempotency, or return behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence conveying the essential action and scope with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and no output schema, yet the description only states the basic action. It does not explain selection of dataType, the role of options, or what response to expect, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 60% of parameters with descriptions (name, options, dataType), but the tool description itself adds no parameter semantics. It does not clarify the meaning of locationId, placeholder, or the dependency of options on dataType, so the description contributes little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'custom field' and scopes it to 'contacts.' This clearly distinguishes it from sibling read tools like ghl_list_custom_fields and other 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?
No explicit when-to-use guidance or exclusions are provided. The context implies usage when a contact custom field needs to be created, but it doesn't mention its relationship to ghl_list_custom_fields 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds no additional behavioral context, such as error handling or return format. It does not contradict annotations but also does not enrich 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 with no wasted words. It is appropriately sized for a simple get 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?
The tool is simple with one parameter and good annotations, but no output schema or mention of what 'details' entails. The description is adequate for basic understanding but could specify the response structure or error 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 only parameter is invoiceId, and the description reinforces that it identifies a specific invoice. With 0% schema description coverage, the description provides minimal compensation, but 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 'Get details of a specific invoice' clearly identifies the verb (get), resource (invoice), and scope (specific). It distinguishes from sibling tools like ghl_list_invoices, which retrieve multiple invoices, and from creation/management 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?
Usage is implied: one would use this when needing details of a single invoice. However, there is no explicit guidance on when to prefer this over ghl_list_invoices or how to obtain the invoiceId. The context is clear but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, clearly establishing a safe read operation. The description adds no extra behavioral context beyond 'specific' and 'details'—no mention of response format, errors, or pagination. It is consistent with annotations and adds minimal value.
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, succinct sentence with no filler. The verb and object are placed right at the start, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with strong annotations, the description is workable but lacks specificity about what 'details' include. There is no output schema, so the agent cannot infer the returned order structure. It would benefit from mentioning that it returns the full order object or key fields.
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 covers the only parameter, orderId, with a description 'Order ID'. The tool description adds no additional meaning about the parameter, such as format or source, so it does not exceed the schema's existing 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 'Get details of a specific payment order' clearly identifies the action (get details) and resource (payment order). It distinguishes itself from sibling ghl_list_orders by emphasizing specificity, and from ghl_get_invoice by naming the exact 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'specific' implies the tool is for retrieving one order by ID, but there is no explicit guidance on when to use this versus ghl_list_orders or other getters. No alternatives are named, so usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description does not need to restate safety. It adds the contextual detail that custom fields are scoped to contacts and a location, but does not disclose behavior like default location handling or pagination, which would be valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence: 'Get all custom fields for contacts in a location.' Every word earns its place, and it avoids restating 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?
Given the simplicity of the tool (one parameter), the rich annotations, and the absence of an output schema, the description is mostly sufficient. It implies a list of custom fields but does not specify the response structure or pagination. Still, for a read-only, open-world list operation, it is adequately 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?
The schema has one parameter, locationId, with zero description coverage. The description mentions 'location' but does not explain the parameter's meaning, optionality, or format. Since the parameter is not required and the description fails to compensate for the schema gap, it leaves the agent uncertain about how and when to provide 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 'Get all' and clearly identifies the resource as 'custom fields for contacts in a location,' differentiating it from sibling list tools like ghl_list_pipelines. The scope 'for contacts' adds useful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description—use to retrieve custom fields—but there is no explicit guidance on when to choose this over alternatives, nor any mention of exclusions or prerequisites. The description does not reference sibling tools or alternative methods.
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 destructiveHint=false, so the description is consistent and adds no contradiction. It adds the scoping detail 'for a location,' but does not disclose additional behaviors like pagination, response format, or the optionality of locationId. With annotations covering the safety profile, a 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?
The description is a single sentence, front-loaded with the verb, and contains no wasted words. It is concise without being under-specified, unlike a pure tautology like 'Process.'
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's simplicity (one optional parameter, no output schema), the description is adequate but has gaps. It does not explain the return structure or the effect of omitting locationId, and the optionality is ambiguous. Annotations compensate for the read-only safety, but more details on parameters and response 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 has one parameter (locationId) with 0% description coverage, so the description must compensate. 'for a location' suggests the role of locationId but does not explicitly name it, nor does it clarify that locationId is optional per schema or what happens if omitted. This is partial compensation but leaves 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 'Get all surveys for a location' uses a specific verb ('Get') and resource ('surveys'), with a clear scope ('for a location'). It clearly distinguishes from sibling list tools like ghl_list_pipelines or ghl_list_campaigns, and is not a tautology of the title '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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (list surveys for a location) but provides no explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or comparisons to similar list tools, such as 'use this when you need survey data, not pipeline data.'
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, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds 'all' and 'location' context, but it does not disclose potential pagination, response format, or behavior when locationId is omitted. With annotations covering safety, a 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?
The description is a single, front-loaded sentence of seven words. Every word contributes to clarity, with no redundant 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?
The tool is simple (one optional parameter, no output schema), and annotations cover safety. However, the description lacks details about response format or behavior without locationId, which could lead to incorrect assumptions. Some additional context on return values or locationId handling 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 0%, so the description must compensate. It does mention 'for a location,' which explains the locationId parameter's purpose. However, it doesn't note that the parameter is optional (per schema) or what happens if it's not provided, leaving a semantic 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 'Get all workflows/automations for a location' uses a specific verb (get/list) and clearly identifies the resource (workflows/automations), distinguishing it from sibling list tools like ghl_list_pipelines and ghl_list_campaigns by naming the exact entity type.
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: it's the tool for retrieving workflows for a location. However, there is no explicit guidance on when to use this tool versus alternatives, nor any mention of exclusions or special conditions. The 'for a location' clause hints at the scope but doesn't clarify optionality or fallback behavior.
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 indicate a write operation (readOnlyHint=false) but are otherwise not conflictive. The description adds useful behavioral context: message body differences for SMS/WhatsApp vs email, subject requirement for email, scheduling via timestamp, and return output. It does not disclose side effects like conversation auto-creation (mentioned only in schema), rate limits, or failure modes, leaving room for improvement.
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 well-structured: a purpose sentence followed by a compact arg list and return statement. It is appropriately sized and front-loaded, but a few entries (e.g., emailFrom) are redundant with schema descriptions and could be trimmed without losing 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 moderately complex (10 params, 2 required) with no output schema. The description covers 7 of 10 parameters and the return shape, which is sufficient given that the remaining 3 are described in the schema. It lacks prerequisites or typical use examples, but it is reasonably complete for a send action.
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 clarifies parameter behavior beyond the schema: it lists valid type values, explains that message is text for SMS/WhatsApp but HTML for email, notes subject is required for Email, and mentions html as an alternative to message. This adds meaningful context to what the schema already provides (90% coverage), warranting above-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 starts with a clear statement: 'Send a message (SMS, Email, WhatsApp, or other) to a contact via GoHighLevel.' This names the action, resource (messages/contact), and channel options, distinguishing it from siblings like ghl_get_messages or ghl_cancel_scheduled_message.
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 explicit guidance on when to use this tool versus alternatives. The description only lists parameters; it does not mention situations where one might prefer ghl_send_invoice, ghl_create_social_post, or other messaging-related tools. Usage context is implied but never stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which covers basic safety. The description adds no extra behavioral context beyond stating the action, such as whether tags are appended or replaced, or how idempotency manifests. 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?
The description is a single concise sentence with no filler or redundancy. It front-loads the core action and includes the nuance 'one or more' which adds value without excess length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required parameters, no output schema, and annotations covering safety, this description is adequate for selection and invocation. It could optionally mention duplicate handling or return values, but given the simplicity and annotation support, the current description is complete enough.
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 for parameters is 100%, with 'contactId' described as 'Contact ID' and 'tags' as 'Tags to add'. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add one or more tags to a contact' uses a specific verb (add) and resource (tags to a contact), clearly distinguishing it from the sibling tool ghl_remove_contact_tags. It conveys exactly what action is performed and on what entity, leaving no ambiguity.
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 the user wants to attach tags to a contact, but provides no explicit guidance on when to use this tool over alternatives, nor any exclusions. The sibling name ghl_remove_contact_tags offers a natural contrast, but the description does not mention it or any other alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=false, so the agent knows this is a state-changing operation. The description adds no additional behavioral context such as whether the invoice is created as a draft, requires the contact to exist, or has external side effects (openWorldHint). 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?
The description is a single sentence that is front-loaded and free of redundancy. It conveys the core purpose with minimal words.
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 6 parameters, a nested items array, and no output schema, a one-sentence description is insufficient. It does not mention what the tool returns, preconditions (e.g., contact existence), or any special behavior around invoice creation. The complexity is higher than the description addresses.
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 covers 67% of parameters with descriptions (name, items, dueDate, contactId). The description only adds 'for a contact', which adds little beyond the schema. It does not clarify the undocumented locationId or currency 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 'Create a new invoice for a contact' uses a specific verb (create) and resource (invoice) with the target (contact). It clearly distinguishes from sibling tools like ghl_get_invoice, ghl_list_invoices, ghl_send_invoice, and ghl_void_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 clearly implies use when creating a new invoice for a contact, which is distinct from sending, listing, or voiding invoices. However, it does not explicitly state when not to use this tool or mention alternatives, but the context is clear enough for an AI agent.
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 agent knows this is a write operation. The description adds the 'schedule or publish' nuance, which clarifies immediate vs. delayed execution. However, it doesn't disclose other behavioral details like idempotency, rate limits, or required permissions, but annotations cover the primary 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?
The description is a single, efficient sentence that clearly communicates the core action without redundant information. It front-loads the purpose and avoids any unnecessary elaboration.
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 relatively simple with 5 parameters and no output schema. The schema descriptions cover most parameter semantics, and annotations provide safety context. The description, while minimal, combined with the schema and annotations gives a complete picture for an agent to invoke this tool correctly. A minor gap is not explaining what the response contains, but for a create/schedule operation this is typically 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 coverage is 80%, so most parameters have descriptions. The description itself adds no additional parameter semantics beyond the schema. The 'scheduledDate' parameter already has a clear description ('omit for immediate publish') in the schema, and the description doesn't enhance it further.
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 ('Schedule or publish') and a clear resource ('social media post'), making it obvious this is a creation/scheduling action. It distinguishes itself from sibling list tools like ghl_list_social_posts and ghl_list_social_accounts by indicating it performs a write operation.
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 clearly implies when to use this tool (to create or schedule a post) versus listing posts, but it does not explicitly state alternatives or exclusions. There's no guidance on when to choose this over other creation tools, though the resource 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 indicate a safe, read-only, idempotent operation. The description adds 'with metadata,' hinting at the return payload, but does not detail response behavior (e.g., not-found handling). This is acceptable for such a simple getter, but not particularly 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, front-loaded sentence with zero redundancy. Every word contributes to understanding 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?
Given the simplicity of the tool (one parameter, read-only, no output schema) and the strong annotation coverage, the description is largely complete. It clearly states the single operation, and the sibling context suggests alternatives. Minor gap: no explicit mention of return value structure or error behavior, but this is not critical for a get-by-ID 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 covers the sole parameter conversationId with a clear description ('Conversation ID'), achieving 100% schema coverage. The tool description adds no additional parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Get a single conversation by ID with metadata.' It identifies the resource (conversation) and the mode of access (by ID), which distinguishes it from sibling tools like ghl_search_conversations and ghl_get_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: use this tool when you have a specific conversation ID. However, it does not explicitly mention when to use alternatives like ghl_search_conversations or provide exclusions, so guidance is minimal but not misleading.
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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond the date-range scoping, which is already evident from the parameters. It does not disclose return format, timezone handling, or potential 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, front-loaded sentence that directly states the tool's function. Every word earns its place, with no filler or redundant 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 is a simple read-only operation with good annotation coverage and fully documented parameters. The description adequately conveys the core purpose, and while it does not describe the output schema (none provided) or timezone nuances, it is complete enough for the tool's apparent simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all four parameters (100% coverage), so the schema does the heavy lifting. The description only reiterates the concept of 'date range' without adding further semantic detail about timezone or calendarId, giving no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get available booking slots' for a calendar. It clearly distinguishes this from sibling tools like ghl_get_events or ghl_get_calendar, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 free slots rather than events or calendar details, but it does not explicitly state when to use this tool over alternatives. No exclusions or prerequisites are mentioned, so it falls short of strong 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds that it returns 'all' pipelines and includes stages, which is useful. However, it does not explain behavior when the optional locationId is omitted, nor does it mention pagination or return format—gaps that annotations don't fill.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, with zero wasted words. It efficiently conveys the core functionality.
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 tool with one optional parameter and no output schema. The description provides enough for basic understanding, but the optional parameter's behavior and the exact return structure (beyond 'pipelines and stages') are not specified. Given the tool's simplicity and strong annotations, a score of 3 is reasonable.
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 mentions 'for a location' which implies locationId is the location, but does not explain that the parameter is optional or what happens if omitted. The name 'locationId' is self-explanatory, but the description adds no meaningful detail beyond that, leaving optionality and format unclear.
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 'Get all pipelines and their stages for a location' with a specific verb (get), resource (pipelines and stages), and scope (per location). This distinguishes it from sibling list tools like ghl_list_surveys and ghl_list_campaigns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is for fetching pipelines and stages for a specific location. While it doesn't explicitly state when not to use it or name alternatives, the resource is unique and the use case is implied. No exclusions are mentioned, 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 cover readability and safety. The description adds behavioral details beyond annotations: paginated results, default location behavior, and advanced filtering capabilities (tags, custom fields). This provides useful context for invocation.
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 compact and well-organized, with a clear opening sentence followed by an Args list and a Returns line. Every line provides relevant information without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core search functionality and return type, but omits the pagination cursor parameters (startAfter, startAfterId) from the Args list, though they appear in the schema. The incorrect filter type also creates a completeness gap. For a tool with no output schema, it is adequate 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?
Although schema coverage is 100%, the description misrepresents the 'filters' parameter as an object while the schema defines it as an array of filter objects. This contradiction can mislead an agent into constructing an invalid argument. The examples of filter capabilities are helpful but the type error overrides that benefit.
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 ('Search contacts in GoHighLevel') and clearly indicates the tool's scope (query, tags, filters, custom fields). It distinguishes itself from sibling tools like ghl_get_contact by being the search-oriented counterpart.
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 finding contacts via various criteria, but it does not explicitly state when to use this tool versus alternatives (e.g., ghl_get_contact for fetching by ID). No exclusions or alternative recommendations are 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=false and destructiveHint=false, so the description doesn't need to repeat those. It adds context by listing 'starred, unread, etc.', but doesn't disclose any additional behaviors like idempotency or side 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, concise sentence that front-loads the core purpose. Every word contributes value, with no redundancy 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 mutation tool with full schema coverage and safety annotations, the description and schema together provide sufficient context. The 'etc.' in the description slightly overpromises beyond the two status fields in the schema, but this is minor and doesn't hinder 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 100%, so all parameters (starred, unreadCount, conversationId) are already documented. The description adds 'starred, unread' but doesn't provide any new meaning beyond the schema's field descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: updating conversation status, with specific examples (starred, unread). The verb 'Update' and resource 'conversation' are explicit, distinguishing it from read-only siblings like ghl_get_conversation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the description, but there is no explicit statement about when to use this tool versus alternatives like sending messages or searching conversations. The description does not mention any exclusions or alternative 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds the location scoping constraint, which is useful behavioral context. However, it does not disclose return format, pagination, or required permissions.
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, front-loaded with action and resource, no redundant details.
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 good annotations, the description is adequate but minimal. It doesn't describe the return structure (array of forms) or any pagination/ordering details, leaving some ambiguity for the agent.
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 0% schema coverage for locationId, the description's phrase 'for a location' gives the parameter meaning, indicating it specifies the location. However, it doesn't clarify whether the parameter is required, its expected format, or what happens if omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all forms for a location' uses a specific verb ('Get all') and resource ('forms'), with clear scope ('for a location'). This differentiates it from sibling tools like ghl_list_pipelines or ghl_get_form_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 clearly indicates when to use the tool: when you need all forms for a specific location. However, it does not explicitly state exclusions or alternatives, such as using ghl_get_form_submissions for submission data, though the resource name makes differentiation straightforward.
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 adds the context that the message was previously scheduled, which implies a future send that can be cancelled. It does not elaborate on side effects or permanence, but the annotations already indicate this is an idempotent, non-read-only, non-destructive operation.
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 no redundant words, quickly conveying 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 tool with one well-described parameter and annotations covering safety, the description is sufficient and not missing essential return-value information since no output schema is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'messageId', and the description does not add any additional meaning beyond the schema's own description.
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 'cancel' and identifies the resource as a previously scheduled message, clearly distinguishing it from related tools like send_message or update_event.
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 for when to use this tool (to cancel a previously scheduled message) but does not explicitly state when not to use it or mention alternative tools. It lacks exclusions or comparisons.
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 and readOnlyHint=false, so the destructive nature is known. The description adds the nuance of permanence ('cannot be undone'), which is a slight enhancement. However, it does not disclose other behaviors like return value or permission requirements.
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 that front-load the action and immediately note irreversibility. No wasted words, perfectly sized for the information conveyed.
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 adequately covers the essential behavior (permanent deletion) for a simple tool with one parameter and no output schema. It could mention the outcome or authorization, but given the tool's simplicity and existing annotations, it is sufficiently 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 100% for the single parameter 'contactId', which already has a clear description. The tool description does not add any parameter-specific details, so it provides no additional value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action (permanently delete) and resource (contact), distinguishing it from sibling tools like update or create. The phrase 'This cannot be undone' adds a critical distinguishing feature, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for permanent deletion, which implies when it should be used. It does not explicitly name alternatives or exclusions, but the intent is obvious and aligns with the tool's 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which fully cover the safety profile. The description adds the location scoping constraint but does not disclose other behavioral aspects like pagination, response shape, or potential rate limits. With strong annotations, the additional value is moderate.
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 of about 12 words. It is front-loaded with the action and resource, contains no filler, and every word contributes to the meaning.
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 strong annotations, descriptive schema, and moderate complexity (6 optional parameters, no output schema), the description covers the essential purpose and constraints. It does not describe pagination or the return structure, but for a simple read-only list operation, the provided information is sufficient for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, with only locationId lacking a description. The description mentions calendar, contact, and date range, which map to the existing schema parameters, but does not add new meaning beyond what the schema already provides. Since coverage is high, the description's marginal value is limited.
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 'Get' with a clear resource 'appointments/events' and scopes it to 'for a location'. It also lists optional filters (calendar, contact, date range), making the purpose unambiguous and distinct from sibling tools like ghl_create_event or ghl_get_calendar.
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 specifying that it retrieves events and lists the available filter dimensions. However, it does not explicitly mention alternatives or when not to use this tool (e.g., for calendar availability use ghl_get_free_slots), so it stops short of explicit 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?
With annotations already declaring readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds valuable context by specifying that only provided fields are changed, meaning omitted fields remain untouched. This goes beyond the annotation's safety profile and helps the agent understand the update semantics, though it does not mention potential side effects like tag list replacement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states the core action and the key usage rule. It is concise, front-loaded, and contains no filler or redundant information, earning a high score for efficiency.
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 16 parameters and no output schema, the description is too sparse. It does not explain return values, error conditions, or the semantics of complex fields like customFields and tags. An agent would lack critical information for correct invocation, such as whether the API returns the updated contact or just an acknowledgment, and how to handle arrays and nested objects.
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 6%, so the description must compensate. It provides a general semantic: 'Only pass fields you want to change' indicates that all fields are optional and represent new values, which is helpful. However, it does not elaborate on specific parameter formats, such as the structure of customFields or how tags are handled (e.g., replace vs. append), leaving ambiguity for many of the 16 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 clearly states 'Update an existing contact' with a specific verb and resource, and it distinguishes itself from sibling tools like create_contact and delete_contact by focusing on modifying an existing entity. The added 'Only pass fields you want to change' clarifies the partial-update semantics, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Only pass fields you want to change' implicitly guides when to use this tool (for updates) and implies not to use it for creation or full replacement. However, it does not explicitly name alternatives, such as using ghl_create_contact for new contacts or ghl_add_contact_tags for tag-specific operations, so the guidance is clear but lacks explicit 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 declare idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: it matches by email/phone and decides to update or create. This goes beyond the annotations and clarifies the side effects. 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 sentence of 21 words, immediately conveying the core behavior without any filler. It is well-structured and front-loaded.
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 primary purpose and update/create logic, but lacks details about parameter meanings, return value, error scenarios, or matching precedence when both email and phone are provided. With no output schema and multiple sibling write tools, more context would be expected for a complete understanding.
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 for 9 undocumented parameters. It only hints that 'email' and 'phone' are matching keys, but does not explain the other parameters (firstName, lastName, tags, source, customFields, etc.). This is insufficient for a 9-parameter tool with no schema descriptions.
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: 'Create or update a contact by email/phone. If a match is found, updates; otherwise creates new.' This uses a specific verb (upsert) and resource (contact), and explains the matching logic, distinguishing it from sibling tools like ghl_create_contact and ghl_update_contact.
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 implicitly conveys when to use this tool: when you want to create or update a contact without knowing if it already exists. It does not explicitly name alternatives, but the upsert behavior is clear. A more explicit mention of 'use instead of create/update when unsure' would elevate this to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and mutation. The description adds value by listing what details are returned (custom fields, tags, activity), which goes beyond annotations but still doesn't address error behavior or response format. With the annotation bar lowered, this is a strong score.
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 redundancy. It front-loads the verb and resource, then lists key detail categories. 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 read tool with one parameter and rich annotations, the description adequately conveys purpose and return scope. No output schema exists, but 'all details including custom fields, tags, and activity' gives a reasonable sense of the response. It doesn't cover edge cases like not found, but that's not critical for context completeness here.
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%, with contactId described as 'The contact ID to retrieve.' The description does not add extra parameter semantics beyond what the schema already provides, 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 uses a specific verb 'Get' with a clear resource 'single contact by ID' and enumerates included details: 'custom fields, tags, and activity.' This distinguishes it from sibling tools like ghl_search_contacts (which searches) and ghl_get_contact_notes or ghl_get_contact_tasks (which retrieve sub-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 description clearly implies usage when you need a single contact by ID, but it does not explicitly state alternatives or exclusions. For example, it doesn't mention that ghl_search_contacts should be used when the ID is unknown. This is clear context without explicit when-not-to-use guidance, so a 4 is appropriate.
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, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds context about the response contents (settings, address, configuration), enriching the behavioral picture 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 a single clear sentence with no unnecessary words, front-loaded with the action and resource. 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 low-complexity read tool with one optional parameter and rich safety annotations, the description is sufficient. It names the resource and key data categories, and no output schema exists to explain return values. The agent can confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter locationId, and the schema already explains 'uses default if omitted'. The tool description does not add extra parameter-level meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('details of a GHL location/sub-account'), and lists concrete content areas (settings, address, configuration). This clearly distinguishes it from sibling tools like ghl_get_location_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 description clearly implies usage for retrieving location details, and no sibling tool serves this exact purpose. However, it does not explicitly state when not to use it or mention alternatives, so it lacks explicit exclusions.
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:

[![ghl-mcp-server MCP server](https://glama.ai/mcp/servers/northrosetech/ghl-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/northrosetech/ghl-mcp-server)

Score Badge

Copy to your README.md:

[![ghl-mcp-server MCP server](https://glama.ai/mcp/servers/northrosetech/ghl-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/northrosetech/ghl-mcp-server)

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/northrosetech/ghl-mcp-server'

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