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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those annotations by specifying the endpoint, the required auth token scope ('Token: location'), and the OAuth scope ('calendars/resources.readonly'), which helps an agent understand authorization requirements. 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.

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

The description is compact and front-loads the core behavior, endpoint, and auth context in a few short lines. Minor redundancy exists in the opening ('List Calendar Resources List calendar resources...'), but the extra tokens about scopes and endpoint are worthwhile, so overall it is appropriately sized.

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

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

For a listing endpoint with four required parameters and no output schema, the description covers the purpose and auth but omits important contextual details: the meaning of limit/skip, response shape, possible defaults, and how this relates to the singular resource sibling. It is adequate but has clear gaps an agent must resolve elsewhere.

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

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

Schema description coverage is only 25%, so the description must compensate. It does name resourceType and locationId as the listing criteria, but it gives no guidance on limit and skip, which are required but only described as generic numbers. Pagination semantics and default behavior are left entirely to inference.

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

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

The description clearly states the action ('List'), the resource ('calendar resources'), and the filtering dimensions ('by resource type and location ID'). It also includes the exact endpoint and is distinguishable from the sibling tool calendars_get_calendar_resource, which returns a single resource rather than listing resources.

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

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

The description implies usage context: call this when listing calendar resources filtered by resourceType and locationId. However, it provides no explicit guidance about when not to use it or which sibling tool should be chosen instead, such as the singular calendars_get_calendar_resource for retrieving one resource.

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

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

The annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the required OAuth scope 'calendars/events.readonly' and the REST path, which is useful context beyond annotations. It does not disclose return format, error behavior, or any side effects, but those are less critical given 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.

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

The description is short but awkwardly constructed: 'Get notification Find Event notification by notificationId' reads like a concatenation of the title and a separate purpose phrase. It front-loads the main intent but wastes a few words on redundancy.

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

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

This is a simple two-parameter read operation, and the description provides the endpoint and scope, which is reasonably complete for a low-complexity tool. However, it lacks context about what an event notification is, how to discover one, or what the response contains, and the absence of an output schema makes those gaps more noticeable.

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

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

Schema description coverage is 0%, so the description must compensate. It mentionse notificationId in text and exposes both calendarId and notificationId as path placeholders in the endpoint, giving some clue. However, it does not explain what calendarId represents or what formats/constraints the values must satisfy, leaving an agent partially guessing.

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

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

The description states a specific verb ('Find'), a resource ('Event notification'), and an identifier ('notificationId'), so the action is clear. The endpoint template reinforces the exact resource being accessed. It does not explicitly differentiate from the similarly named sibling 'calendars_get_event_notification', but the behavior itself is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives, and no mention of exclusions or prerequisites. The description merely states what the tool does, leaving the agent to infer usage context from the endpoint and name.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP GET endpoint, calendars.readonly scope, and pagination support, which enriches the behavioral context beyond the annotations. No contradiction exists.

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

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

The description is short but redundant: it opens with 'List user availability schedule' and then restates 'Retrieve user availability schedules' in the next sentence. The endpoint and scope information is useful, but the repetition could be trimmed without losing meaning.

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

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

For a read-only list operation, the description covers the essential aspects: endpoint, scopes, filters, and pagination. Required parameters and default limits are visible in the schema, and the absence of an output schema is acceptable since the return type is implied to be a list of schedules. The description is sufficient for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, and the description's mention of filters by location, calendar, and user mirrors the schema descriptions without adding new meaning. The baseline of 3 applies because the schema already handles parameter documentation.

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

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

The description clearly states a specific verb ('List'/'Retrieve') and resource ('user availability schedules') and enumerates filters by location, calendar, and user. It does not explicitly contrast with the similar sibling calendars_getschedulebyid, but the plural 'schedules' and 'search' endpoint make the list-oriented purpose clear.

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

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

The description implies usage through the filter list and pagination support, but it does not explicitly state when to choose this tool over alternatives or mention any exclusions. An agent can infer this is the search/list availability tool, but there is no direct guidance on sibling selection.

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

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

Annotations already cover the read-only, idempotent, non-destructive nature. The description adds the required OAuth scope and the exact endpoint, which is useful, but it does not disclose return format, error behavior, or any other notable traits. With annotations present, the bar is lower and 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.

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

The description is short but starts with a redundant repetition of the title ('Get Appointment Get appointment by ID'). It is not poorly structured, but the redundant opening could be trimmed. Overall it is concise but not optimally front-loaded.

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

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

For a simple lookup by ID, the description plus annotations and complete schema are nearly sufficient. However, there is no output schema and no hint of what fields are returned, and the schema's note about 'modify original series' is a confusing distraction in a read-only tool. The description could have clarified the response shape or explicitly routed to calendar event listing tools.

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

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

Schema description coverage is 100% for the only parameter, so the description does not need to compensate. The description itself adds no parameter semantics beyond the endpoint path, but the baseline of 3 is correct when the schema fully documents the parameter.

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

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

The description specifies a clear verb and resource: 'Get appointment by ID' with the explicit endpoint path. It distinguishes itself from the many list/search calendar tools by focusing on a single appointment ID, though it does not explicitly name sibling alternatives.

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

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

Usage is implied: use this tool when you have an event/appointment ID and need that single appointment. However, there is no explicit guidance on when not to use it or which sibling to choose instead (e.g., calendars_get_calendar_events for listing).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the required OAuth scope 'calendars/events.readonly' and the endpoint, which is useful auth context, but it does not disclose pagination behavior, ordering, or what happens when no notes exist.

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

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

The description is short, but it redundantly repeats 'Get Notes Get Appointment Notes', where the first phrase adds nothing. The endpoint path and scope are useful and front-loaded, yet the duplication makes it less polished than necessary.

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

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

For a simple read-only fetch with well-documented parameters and safety annotations, the description is mostly adequate. However, it lacks usage guidance, return-shape expectations (no output schema exists), and any mention of pagination semantics beyond the schema's limit/offset definitions.

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

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

Schema description coverage is 100%, with limit, offset, and appointmentId each having meaningful descriptions. The tool description adds no parameter details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states the exact resource ('Appointment Notes') and operation ('Get') via both the title and the endpoint path '[GET /calendars/appointments/{appointmentId}/notes]'. This clearly distinguishes it from sibling tools like contacts_get_note and contacts_get_all_notes by making the appointment context explicit.

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

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

No guidance is provided about when to use this tool versus alternatives such as calendars_get_appointment or contacts_get_all_notes. The description does not mention exclusions, prerequisites, or conditions that would route an agent to a sibling.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the HTTP method (GET) and the auth scope (calendars/events.readonly), which is useful, but it does not explain what a blocked slot is or what behavior the response will have. No contradiction with annotations exists.

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

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

The description is a single compact sentence with no wasted words, placing the operation and endpoint first followed by the scope. It is appropriately front-loaded, though it is so minimal that it sacrifices explanatory value.

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

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

Given there is no output schema and the tool has six parameters with alternative identity fields, the description is too thin. It does not explain the semantics of blocked slots, clarify the userId/groupId/calendarId relationship, or describe the expected response, leaving important gaps for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are already documented. The tool description adds no additional parameter semantics, and the schema contains a mild tension between the required fields and the 'either userId, groupId or calendarId' notes, which the description does not resolve.

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

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

The description clearly states the operation ('Get Blocked Slots') and the specific resource via the endpoint '/calendars/blocked-slots'. It is distinguishable from siblings like calendars_get_slots by the 'blocked-slots' resource, though it does not explicitly contrast itself with that sibling.

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

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

The description gives no guidance on when to use this tool versus alternatives such as calendars_get_slots or calendars_get_calendar_events. It only provides the endpoint and required OAuth scope, leaving the agent to infer usage from the name alone.

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

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

The description provides the HTTP method, endpoint pattern, and required OAuth scope 'calendars.readonly', which adds useful context beyond the readOnlyHint annotation. It does not describe error behavior or return format, but the annotations already establish the safe, read-only, idempotent nature of 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.

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

The description is short and front-loads the core behavior ('Get calendar by ID') before adding the endpoint and scope. The opening 'Get Calendar' is slightly redundant with the title, but the overall structure is efficient.

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

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

For a simple, single-required-parameter read-only getter, the description is largely complete: it names the resource, the lookup key, the endpoint, and the auth scope. It could be stronger by explicitly routing users away from this tool when they need to list calendars or retrieve calendar events.

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

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

The input schema has 100% description coverage for the only parameter, calendarId, so the description does not need to add much. It simply reinforces that the calendar is fetched by ID but provides no additional format, validation, or usage nuance beyond the schema.

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

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

The description states a clear action and target: 'Get calendar by ID'. It includes the HTTP GET endpoint and specifies that this tool fetches a single calendar, which distinguishes it from list-oriented siblings like calendars_get_calendars.

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

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

The description implies the tool should be used when a calendarId is available, but it does not explicitly state when to use this tool versus alternatives. It also does not mention that listing calendars without an ID should use calendars_get_calendars.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds the HTTP method and the calendars/events.readonly scope, which is useful auth context beyond the annotations, but it does not reveal any further behavioral traits such as result shape, pagination, or timeboundary handling.

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

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

The definition is compact and front-loads the endpoint, but the phrase 'Get Calendar Events' merely restates the tool name and title. It is concise yet nearly redundant, providing little unique structured information beyond the endpoint and scope metadata.

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

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

With 6 parameters, no output schema, and a large sibling set, this description is too thin. It omits the mutual-exclusivity requirement among userId, groupId, and calendarId that the schema 'required' array does not capture in its required list, and it says nothing about the expected return value or failure conditions.

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

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

Input schema description coverage is 100%, and the schema already explains units ('in millis') and the either/or constraint among userId, groupId, and calendarId. The description adds no parameter-specific meaning, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Get Calendar Events') and adds the exact endpoint (GET /calendars/events) and auth scope. This distinguishes it from siblings like calendars_get_calendar or calendars_get_appointment, though it does not explicitly say it returns a list or how those events are scoped.

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

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

There is no guidance on when to use this tool versus the many sibling calendar/conversation/opportunity tools. It does not describe filtering by locationId/time range or the required 'one of userId, groupId, calendarId' rule, so an agent cannot reliably decide between this and calendars_get_slots or calendars_get_appointment.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to re-state safety. It adds valuable invocation context beyond those annotations: HTTP GET, the path structure, token location, and required OAuth scope.

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

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

The description is compact and front-loads the actionable detail in one sentence, then provides auth requirements. The opening phrase 'Get Calendar Resource' is a redundant restatement of the title, which prevents a 5.

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

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

For a simple two-parameter read-only getter, this is complete: the schema documents all inputs, the endpoint defines the resource, and token and scopes cover authorization. An output schema is not necessary to make the call correctly, and annotations already cover safety behavior.

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

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

Schema coverage is 100%, and both parameters have descriptions, with resourceType further constrained by an enum. The description's endpoint template reinforces the parameter roles but adds no semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific operation, 'Get calendar resource by ID', and gives the exact endpoint [GET /calendars/resources/{resourceType}/{id}]. This clearly separates it from nearby getters like calendars_get_calendar_events or calendars_get_appointment.

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

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

The description makes it obvious this tool is for retrieving a single calendar resource by resourceType and id, and the endpoint, token, and scopes define the call context. It does not explicitly name sibling alternatives or say when not to use it, so it falls short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds 'Scopes: calendars.readonly' and the GET endpoint, which provides some authentication context. Still, it does not disclose response shape or pagination behavior, though these are less critical given 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.

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

The description is short and efficient, containing the operation, endpoint, and scope. The only minor flaw is the redundant repetition of the tool title 'Get Calendars' at the start, which wastes a few words without adding information.

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

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

For a simple list operation with strong annotations and a fully documented schema, the description is minimally adequate. It does not explain how to choose between related calendar endpoints or describe the return format, but the core purpose and parameters are clear enough.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description adds no meaning beyond 'location', but because the schema carries the full parameter burden, a baseline score of 3 is appropriate.

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

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

The description states a specific action and resource: 'Get all calendars in a location.' This clearly distinguishes it from siblings like calendars_get_calendar (singular) and calendars_get_calendar_events. Including the endpoint and scopes reinforces the exact operation.

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

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

The context is understandable: use this to list all calendars for a location. However, it does not explicitly say when to prefer this over related calendar endpoints such as calendars_get_calendar or calendars_get_groups, and no alternatives or exclusions are mentioned.

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

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

Annotations already convey readOnly, idempotent, openWorld, and non-destructive behavior. The description adds the HTTP endpoint and the required read-only scope 'calendars/events.readonly', which is useful context. It does not describe pagination, filtering behavior, or the shape of returned notifications, but the annotation coverage lowers the burden.

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

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

The description is short and front-loads the essential endpoint and scope information. The repetition of 'Get notifications' from the title is minor and does not significantly hurt clarity.

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

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

For a tool with five parameters, no output schema, and a close sibling, this description is incomplete. An agent would still not know when to select this over calendars_find_event_notification, how to form a meaningful query, or what the response contains. Annotations cover safety but not usage context.

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

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

Schema description coverage is only 40%, with skip and limit documented but deleted, isActive, and calendarId left to the schema. The description adds that this is a query against /calendars/{calendarId}/notifications, implying calendarId is a path parameter and the rest are query parameters, but it does not explain what deleted or isActive mean or how pagination works.

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

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

The description states a clear verb and resource: 'Get calendar notifications based on query' with a specific endpoint. It identifies the operation as a read on calendar notifications, though it does not explicitly differentiate itself from the similarly named sibling calendars_find_event_notification.

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

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

No guidance is provided about when to use this tool versus alternatives such as calendars_find_event_notification or calendars_get_calendar_events. The phrase 'based on query' implies filtering but gives no concrete selection criteria or exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, but the description adds a specific auth requirement ('Scopes: calendars/groups.readonly'), which is useful beyond the annotations. It also clarifies the operation is scoped to a location and returns all groups, adding behavioral context without contradicting the annotations.

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

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

The description is short, but it begins with the redundant phrase 'Get Groups' which merely repeats the tool name and title. The substantive information is front-loaded afterward, and the endpoint/scopes line is useful but could be more tightly integrated without the initial redundancy.

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

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

For a simple read-only list operation with one required parameter and rich annotations, the description covers the necessary invocation context: resource type, location scope, endpoint, and required auth scope. It does not describe the response shape or pagination, but the low complexity and open-world annotation lessen that gap.

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

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

Schema coverage is 100%, so the single required parameter locationId is already documented. The description reinforces that the operation is location-scoped but does not add new semantic detail such as accepted formats or additional constraints, so the baseline score applies.

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

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

The description clearly states a specific action and resource: 'Get all calendar groups in a location.' This is more specific than the tool title and distinguishes this endpoint from siblings like calendars_get_calendars or calendars_get_calendar, which operate on calendars rather than calendar groups.

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

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

The description implies its use case: retrieve calendar groups for a given location. However, it provides no explicit guidance about when to prefer this tool over sibling tools, nor does it mention exclusions or related endpoints. The context is clear but alternatives are not addressed.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's additional disclosure burden is modest. It adds useful context by specifying the endpoint, required scope ('calendars.readonly'), and the type of data returned, but it does not describe edge cases, error behavior, or response format.

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

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

The core description is short and front-loaded with the retrieval purpose. However, the opening phrase 'Get user availability schedule' duplicates the tool title before the real sentence begins, which is minor redundancy that prevents a perfect score.

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

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

For a simple, one-parameter get-by-id tool, the description is complete: it names the resource, the identifier parameter, the endpoint, the required scope, and the kind of information returned. The rich annotations also cover safety and idempotency, so nothing critical is missing.

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

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

The schema covers 100% of the single parameter and describes it as the unique identifier of the schedule. The description echoes this without adding new semantics such as format, examples, or constraints, so it remains at baseline.

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

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

The description uses a specific verb ('Retrieve') and clearly identifies the resource ('a specific schedule by its unique identifier'). It also lists the return contents (rules, timezone, associated calendars/users), which makes the tool's purpose unambiguous and distinguishable from sibling list-style tools like calendars_getallschedules.

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

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

The description makes the intended use clear: call this when you have a schedule's unique identifier and need its detailed data. It does not explicitly name alternatives or exclusions, but the id-based retrieval pattern is self-evident given the endpoint and sibling tools.

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

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

Beyond the readOnlyHint and non-destructive annotations, the description adds useful context: the HTTP method, the exact endpoint, and the required OAuth scope 'calendars.readonly'. This helps an agent understand auth expectations and that the operation is a safe read.

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

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

The description is short and mostly to the point, but it opens with the redundant phrase 'Get Free Slots' immediately followed by 'Get free slots...'. The optional-filter sentence is also wordier than necessary, though the endpoint and scope are useful additions.

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

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

With full schema documentation for all parameters, read-only annotations, and the endpoint and scopes included in the description, an agent has enough information to select and invoke the tool successfully. The lack of an output schema is mitigated by the simple nature of the operation.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds little beyond restating that timezone and user filters are optional, and it does not clarify the relationship between userId and userIds.

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

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

The description clearly states the tool gets free slots for a calendar within a date range, which is a specific verb and resource. It includes the REST endpoint and optional filters, making the purpose apparent, though it does not explicitly differentiate from sibling tools like calendars_get_blocked_slots.

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

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

No guidance is given about when to use this tool versus alternatives such as calendars_get_blocked_slots or calendars_get_calendar_events. The description mentions optional timezone and user filters, but that is parameter information, not usage direction.

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

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

Read-only behavior is already covered by annotations (readOnlyHint=true). The description adds useful context by specifying the POST endpoint and required calendars/groups.write scope, which are not available in annotations or schema.

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

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

The description is short and includes helpful endpoint/scope details, but it opens with 'Validate group slug', which repeats the title and the next sentence. The redundant phrase could be removed without losing meaning.

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

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

For a simple two-parameter validation tool, the description supplies endpoint, method, scopes, and the outcome it reports. It does not specify the exact response shape, but 'available or not' conveys the intended result, and no output schema is present.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds little beyond the slug's role in availability, and locationId remains minimally explained, but no compensation is required at this coverage level.

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

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

The description names the exact resource (group slug) and the specific action: checking availability. It is clearly distinct from siblings like calendars_get_groups, which list groups rather than validating a slug.

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

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

The purpose implies the tool is for availability checks, so an agent can infer when to use it, but there is no explicit guidance on prerequisites, timing (e.g., before creating a group), or when not to use it versus related calendar tools. No alternatives are named.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds the HTTP method, path, and auth scope ('contacts.readonly'), which is useful, but it does not disclose pagination, ordering, or return shape.

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

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

The description is a single compact line that front-loads the operation and endpoint, then gives the required scope. There is no filler or redundant wording.

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

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

For a one-parameter read-only endpoint with rich annotations, the description is largely sufficient: an agent knows what to call and with what permission. It could be more complete by naming the singular alternative or stating return behavior, but the core calling context is present.

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

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

The schema covers 100% of the single parameter with a 'Contact Id' description, so no extra parameter detail is required. The description adds no additional semantic value beyond what the schema already provides.

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

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

The description states the operation ('Get All Notes') and the exact endpoint, making clear this retrieves all notes for a contact. It is distinguishable from contacts_get_note by the plural 'All Notes,' though it does not explicitly name that sibling.

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

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

No guidance is given about when to choose this tool over contacts_get_note or other note-related endpoints. The usage must be inferred from the tool name and endpoint path.

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

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

Annotations already cover read-only, non-destructive, idempotent behavior. The description adds the concrete HTTP method and required scope 'contacts.readonly', which is useful auth context beyond annotations. Pagination and response details are not mentioned, but the annotation coverage lowers that burden.

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

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

One compact line containing the operation, endpoint, and scope with no filler. The key information is front-loaded and every element earns its place.

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

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

This is a simple one-parameter read operation with rich annotations and an explicit endpoint/scope, so it can be invoked correctly without additional details. It omits return-shape or pagination details, but for a straightforward list operation these are less critical.

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

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

The single parameter contactId is fully documented in the schema with 100% coverage, so the description need not repeat it. The path template clarifies that contactId is a path parameter, but this adds only marginal value over the schema.

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

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

States a specific verb ('Get'), resource ('all Tasks'), and the REST endpoint scoped to a contact. The plural 'all Tasks' differentiates it from the singular sibling contacts_get_task.

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

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

Usage is implied by the name and endpoint: retrieve every task for a contact. However, there is no explicit when-to-use or when-not-to-use guidance, nor any reference to alternatives like contacts_get_task.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior; the description adds the concrete OAuth scope 'contacts.readonly' and the HTTP verb, which are useful for invocation. It does not describe pagination or return shape, but the annotation coverage lowers the burden on the description.

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

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

The description is a single compact line containing the operation, resource path, and required scopes. Every element earns its place, and the core purpose is front-loaded with no filler.

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

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

For a simple GET operation with one required parameter and strong annotations, the description plus schema is sufficient to construct a correct call. There is no output schema and no detailed return-value description, but the plural 'Appointments' conveys the general result and the other gaps are minor.

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

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

Schema description coverage is 100%, so contactId is already documented as 'Contact Id'. The description adds no additional meaning about the parameter's format, source, or constraints, so it does not improve on the schema.

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

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

The description explicitly states 'Get Appointments for Contact' and gives the exact REST path, making the operation unambiguous. It clearly distinguishes itself from sibling calendar/appointment tools by tying the operation to a contactId resource.

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

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

The path and title imply the tool is for retrieving a contact's appointments, but the description gives no explicit when-to-use guidance or alternatives. With many sibling tools available, an agent must infer selection from the name and endpoint rather than from stated criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the HTTP method and the required OAuth scope contacts.readonly, which is useful authorization context beyond the annotations. It does not describe error behavior or return format, but for a simple read-only GET this is a reasonable level of disclosure.

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

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

The description is extremely short and front-loads the endpoint and scope, which are the most actionable details. The phrase 'Get Contact' redundantly repeats the title, but this is minor and does not meaningfully hurt the definition.

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

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

For a one-parameter read-only GET with full schema coverage and strong safety annotations, the endpoint and scope are sufficient for an agent to invoke the tool correctly. It does not explain response contents, but no output schema exists and the operation is simple enough that this is an acceptable gap.

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

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

The only parameter, contactId, is already 100% documented in the schema as 'Contact Id'. The description adds no additional semantics about path vs query usage, format expectations, or edge cases, so the schema carries the full burden and the baseline of 3 applies.

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

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

The description states a concrete resource ('contact by ID'), the HTTP verb GET, and the exact endpoint path, which is more specific than the title alone. However, it does not explicitly differentiate this tool from sibling tools like contacts_get_duplicate_contact or contacts_get_contacts, leaving some ambiguity about the exact use case.

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

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

The description provides no guidance on when to use this tool versus searching for contacts or retrieving related contact data. It only notes the required scope, with no when-to-use, prerequisites, or alternative recommendations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which establish the safety profile. The description adds valuable context beyond those hints: the endpoint is deprecated, the HTTP verb is GET, and the required OAuth scope is contacts.readonly. This helps the agent understand operational constraints that the annotations do not convey.

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

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

The description is short and front-loads the key deprecation warning, but it repeats 'DEPRECATED' both in the note and at the end. The markdown link is useful for humans but adds little for an AI agent. Overall it earns a mid score because it is efficient despite minor redundancy.

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

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

For a deprecated tool with strong read-only annotations and 100% schema coverage, the description provides the most critical contextual fact: do not use this, use Search Contacts instead. The lack of an output schema is mitigated because the tool is effectively superseded. It could have mentioned pagination behavior or response shape, but the deprecation guidance makes the description sufficient for agent decision-making.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, which sets the baseline at 3. The description itself adds no parameter-level meaning beyond what the schema provides. Some schema descriptions are thin (e.g., 'Start Afte' typo and 'Contact Query'), but the description does not compensate for those gaps.

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

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

The description clearly identifies the operation as 'Get Contacts' with the endpoint 'GET /contacts/', so an agent can tell it is a contact-list retrieval tool. It also names the deprecated status and points to 'Search Contacts' as the replacement, which helps distinguish it from the sibling contacts_search_contacts_advanced. However, it does not describe exactly what contacts are returned or the listing scope beyond the endpoint.

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

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

The description gives an explicit usage directive: this endpoint is deprecated and the agent should use the Search Contacts endpoint instead. It names the exact alternative, so there is no ambiguity about when to prefer another tool. This is strong, actionable guidance.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds useful behavioral context by exposing the HTTP method '[GET ...]' and the auth requirement 'Scopes: contacts.readonly'. It could include response/pagination behavior, but that is minor given the strong annotation coverage.

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

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

The description is a single, dense sentence containing the operation, endpoint, and required scope. It is front-loaded and contains no filler or redundant prose.

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

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

Given five parameters, two required, no output schema, and minimal parameter documentation, this description is not complete enough for reliable invocation. It leaves the role of locationId unexplained and says nothing about what response shape will come back or how pagination works.

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

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

Schema description coverage is only 40% and the description adds almost no parameter meaning beyond what the schema names. The endpoint clarifies that businessId is a path parameter, but it never explains the required locationId, the query param, or the meaning of skip and limit. This is a significant gap for actually invoking the tool.

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

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

The description names a specific operation and resource, 'Get Contacts By BusinessId', and pins it to an exact endpoint, 'GET /contacts/business/{businessId}'. This clearly distinguishes it from sibling contact tools like contacts_get_contact or contacts_get_contacts because it identifies the businessId filter.

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

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

Usage context is implied by the name and endpoint: an agent would use this when it has a businessId and needs the contacts associated with it. However, the description gives no explicit guidance about when to prefer this over contacts_get_contacts or contacts_search_contacts_advanced, and no exclusions or prerequisites beyond the listed scope.

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

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

Annotations already declare read-only and idempotent behavior; the description adds conditional search behavior, the endpoint, and the required auth scope contacts.readonly, which is useful context beyond the annotations. No contradiction exists.

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

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

The substantive conditional behavior, endpoint, and scope are compact, but the opening sentence 'Get Duplicate Contact .' simply repeats the title and adds no value. Structure is acceptable but not tightly front-loaded.

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

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

For a simple read-only search with fully documented schema and rich annotations, the description supplies the endpoint, search priority, and auth scope needed to invoke it. It does not describe return format, and the global-unique-identifier reference is slightly underspecified, but these are minor gaps for invocation.

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

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

The schema already documents all three parameters (100% coverage), and the description adds meaningful semantics by defining email and phone priority and tying them to the Allow Duplicate Contact setting. The mapping of the 'global unique identifier' to an actual parameter remains somewhat ambiguous.

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

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

The description identifies the resource as duplicate contacts and includes the exact endpoint GET /contacts/search/duplicate, so the tool's purpose is clear. It does not explicitly contrast with sibling tools like contacts_get_contact or contacts_search_contacts_advanced, so it misses full differentiation.

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

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

The setting-dependent search priority tells an agent how search keys behave (email then phone when duplicates are allowed, unique identifier otherwise), but it does not state when to prefer this tool over sibling search/get tools. Selection guidance remains mostly implied by the name and endpoint.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds the OAuth scope `contacts.readonly`, which is useful authorization context beyond the annotations, but it does not describe error behavior or response semantics. No contradiction with annotations.

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

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

The description is one short sentence containing the endpoint and scopes, with no filler or redundant explanations. It is front-loaded with the verb and resource. This is appropriately concise.

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

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

For a simple two-parameter read-only GET, the combination of description, schema, and annotations is adequate to construct a valid request. It lacks an explicit return-value description, but that is a minor gap given no output schema and the simplicity of the operation. The main omission is guidance on choosing between this and the plural note-list sibling.

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

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

The input schema provides descriptions for both parameters (`Note Id`, `Contact Id`), covering all parameters. The URL template reinforces the relationship between contactId and id, but the description adds no format or constraint details. Baseline 3 applies for high schema coverage.

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

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

The description provides an HTTP GET endpoint and resource path `/contacts/{contactId}/notes/{id}`, which specifies a single note retrieval. This distinguishes it from the sibling `contacts_get_all_notes` by its singular resource and ID parameter, though it does not explicitly state that distinction. The phrasing is clear but closely mirrors the tool name.

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

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

No guidance is given about when to use this tool versus `contacts_get_all_notes` or other sibling getters. The description only states the operation and scopes, leaving the agent to infer selection criteria from naming conventions. This is a no-guidance situation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds the HTTP method and required OAuth scope, but does not disclose response shape, error behavior, or any other behavioral nuances beyond what annotations provide.

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

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

The description is a single compact sentence that includes the endpoint and scopes without any unnecessary wording. Every element earns its place and it is immediately scannable.

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

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

For a straightforward two-parameter read operation, the endpoint, scope, and annotations provide most necessary context. However, the missing guidance about when to use this versus contacts_get_all_tasks leaves a small but relevant completeness gap, especially since there is no output schema to clarify expected returns.

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

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

Schema description coverage is 100%, and both parameters are individually described, albeit minimally. The tool description adds no extra parameter meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly identifies a specific operation: retrieving a single task via 'Get Task' and the exact endpoint path. It is distinguishable from siblings like contacts_get_all_tasks by the composite resource path, though it does not explicitly state that distinction.

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

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

No explicit guidance is given for when to use this tool versus alternatives such as contacts_get_all_tasks or contacts_get_note. The endpoint implies retrieving one task by contactId and taskId, but the tool description does not state when it should be selected over related getters.

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

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

Annotations already cover read-only, non-destructive, and open-world behavior, so the description only needs to add context. It adds the endpoint [POST /contacts/search], the required scope contacts.readonly, and a documentation link, which is useful but does not describe response shape, pagination, or filtering behavior.

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

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

The description is short and mostly readable, but it opens with a redundant 'Search Contacts' that repeats the title before providing real content. The endpoint and scope line is useful, though the overall structure is slightly clumsy with a long inline documentation link.

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

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

For an advanced search endpoint with a completely undefined request body and no output schema, this description is not complete enough. It provides the endpoint, scope, and a docs link, but omits any details about the available filters, required body fields, pagination, or return values, which are critical for correct invocation.

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

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

The input schema exposes only an opaque 'body' object with no defined properties and only the generic description 'Full request body'. The tool description mentions 'advanced filters' but does not enumerate filter fields, value formats, or example structures, so an agent cannot confidently construct a valid request body.

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

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

The description clearly states the tool searches contacts using combinations of advanced filters, with a specific verb and resource. It is more specific than the title alone and hints at how it differs from simpler list/get contact siblings, though it does not explicitly name an alternative.

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

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

The phrase 'combinations of advanced filters' implies usage when a caller needs complex contact search beyond simple retrieval, but there is no explicit when-to-use/when-not-to-use guidance or mention of alternative contact tools. Usage context is only implied, so it does not fully route an agent.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds useful context such as the token requirement, scopes, and endpoint. However, it does not mention the response format or what happens when a transcription is unavailable, so it only partially supplements 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.

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

The description opens by repeating the title verbatim ('Download transcription by Message ID') and then immediately restates the same idea. The endpoint and scopes are useful, but the first phrase is redundant and adds noise rather than value.

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

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

The tool is simple and annotations cover safety, but the description fails to differentiate this from conversations_get_message_transcription or explain what the downloaded payload looks like. With no output schema, that missing distinction and response clarity are important gaps.

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

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

Schema description coverage is 100%, so both messageId and locationId are already explained as strings. The description restates the message ID concept but adds no real semantic detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Download the recording transcription for a message by passing the message id', and includes the exact endpoint. It is clear about what the tool does, but it does not distinguish itself from the similarly named sibling conversations_get_message_transcription.

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

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

There is no guidance about when to use this tool versus conversations_get_message_transcription or conversations_get_message_recording. The description only explains the action and auth scopes, leaving the selection decision entirely to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: cursor-based pagination mechanics, the presence of messageType/source/subType fields in the response, the default channel behavior that includes activity messages, and required OAuth scope. This gives an agent a solid behavioral model before calling.

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

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

The description is compact and front-loaded with the core purpose, then adds pagination, response fields, and channel default in a logical order. It loses a point because 'Export messages by location ID' is immediately repeated in the next sentence, creating mild redundancy.

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

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

For a 10-parameter export tool with no output schema, the description covers the essentials: pagination via cursor, default channel behavior, key response fields, and required scope. The remaining gaps (date format, sorting defaults) are already covered by schema descriptions. It is slightly short of complete because it does not describe the overall response envelope.

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

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

Schema description coverage is 100%, so the schema fully documents all ten parameters. The description adds some value by explaining the channel default and pagination cursor pattern, but largely restates what the schema already conveys. A baseline 3 is appropriate given the strong schema coverage.

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

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

Description opens with a specific verb-resource pair: 'Export messages' for a specific location, and is further clarified by cursor-based pagination and the explicit GET endpoint. It is clearly distinguishable from sibling tools like conversations_get_messages because it frames the operation as a location-scoped export rather than a general message retrieval.

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

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

The description clearly states this tool exports messages for a specific location, which orients the agent toward its intended scope. It also explains the channel parameter's default behavior, letting the agent know when to pass it. However, it does not explicitly contrast this with sibling tools or state when NOT to use it.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructiveness, so the safety profile is covered. The description adds minor context by specifying location scoping and the exact GET endpoint, but it does not disclose pagination, response shape, or any unusual behavior.

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

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

The description is short, but it begins with 'Get All Custom Subtypes', an exact duplication of the title, before adding the actual sentence. That redundancy wastes the opening slot and does not earn its place.

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

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

For a simple, read-only, single-parameter tool, the description plus schema and annotations give enough to call the endpoint. However, the absence of an output schema and any explanation of what 'custom subtypes' are leaves some ambiguity about the expected response.

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

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

Schema description coverage is 100%, with locationId described as 'Location Id'. The description adds no parameter-level detail beyond that, which is acceptable since the schema already provides the only parameter's meaning.

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

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

The description states a specific verb and resource: 'Get all custom subtypes for a location', which is clear and useful. However, it repeats the tool title almost verbatim and does not explicitly distinguish this endpoint from sibling getter tools.

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

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

No guidance is given about when to use this tool versus other conversation or location getter tools. It does not mention prerequisites, alternatives, or exclusions, so an agent must infer context purely from the name and parameter.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the behavioral distinction of returning statuses for all emails or a specific email, but does not disclose response shape, pagination, or error behavior. That is acceptable given annotations, but not rich.

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

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

The description is short but contains redundancy: 'Get Contact Unsubscription Status' duplicates the tool title and adds no information. The useful content, 'Get all subscription statuses for a contact (all emails or specific email)' plus the endpoint, is compact but could be cleaner.

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

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

For a simple read-only GET tool with well-documented parameters and safety annotations, the description is largely sufficient. It clarifies the optional email behavior and result scope, though it could additionally note what a successful response contains. Given no output schema, this is a minor gap rather than a critical one.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only marginal value by reinforcing the optional email behavior, which is already present in the schema. Baseline 3 is appropriate here.

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

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

The description states a specific action ('Get') on a clear resource ('subscription statuses for a contact') and clarifies the scope (all emails or a specific email). It is not explicitly differentiated from siblings, but no sibling covers the same resource, so the purpose is nonetheless clear.

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

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

The description implies this tool is for retrieving subscription statuses, and the optional email parameter gives a meaningful usage variation (all emails vs. specific email). However, it does not explicitly state when to choose this tool over alternatives or mention any exclusions.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the required scope (conversations.readonly) and the GET endpoint, which provides useful context beyond annotations. No contradictions; the description aligns with the read-only nature.

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

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

The description is short but begins with a redundant repetition of the title ('Get Conversation') before stating the actual purpose. It could be more concise and front-loaded by removing the redundant prefix. No excessive length, but structure could be improved.

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

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

For a simple get-by-ID tool with one parameter, no output schema, and a rich annotation set, the description provides enough context: it specifies the endpoint, scopes, and purpose. It doesn't need to explain return values or error handling for a tool this straightforward, so it is adequately complete.

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

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

The schema fully describes the only parameter (conversationId as string, 100% coverage). The description offers no additional meaning about the parameter, so the baseline of 3 applies. Not adding extra detail is acceptable given the schema's completeness.

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

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

The description clearly states the tool retrieves conversation details by ID, with the endpoint and scopes. It distinguishes itself from search tools by relying on the ID, though it doesn't explicitly contrast with siblings like conversations_search_conversation. The redundancy of repeating 'Get Conversation' at the start slightly detracts from precision.

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

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

No guidance is provided on when to use this tool versus alternatives such as conversations_search_conversation or conversations_get_messages. The intended use case (having a conversationId) is implied but never stated, so an agent might not know when to prefer this over a search.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description only adds the HTTP GET path, which mostly restates the annotations and does not disclose response shape, required authorization, or any other behavioral details.

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

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

The description is very short and front-loaded, but the main phrase is a direct repetition of the title. The endpoint path is the only genuinely additive piece; the rest is redundant.

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

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

For a read-only fetch tool with no output schema, the description should at least state what is returned, such as the email message details, headers, or body. It does not, and it also fails to clarify how this relates to sibling message tools, leaving the agent with only the bare endpoint.

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

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

The input schema is empty, and with zero parameters the baseline is 4. The description does add some value by exposing the {id} path parameter in the endpoint, signaling that an identifier is required even though the schema does not list it.

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

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

The description restates the title verbatim and adds the REST path. It clearly identifies the resource as an email message retrieved by ID, but it does not explain what an 'email' is in this context or how this tool differs from siblings like conversations_get_message or conversations_get_messages.

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

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

There is no guidance about when to use this tool versus alternatives. The sibling list contains several related message-fetching tools, but the description gives no conditions, exclusions, or selection criteria.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the HTTP method and required OAuth scope, which is useful auth context, but does not describe response format, error behavior, or other runtime traits.

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

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

The description is short and front-loaded with the core action, followed by the endpoint and scope. It is slightly redundant with the title, but the endpoint and scope information earns its place.

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

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

For a simple read-only fetch, the description covers the action, endpoint, and auth scope. However, because the input schema exposes no parameters, the description should more explicitly state that a message ID is required and how it is supplied; it also does not clarify the relationship with conversations_get_messages.

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

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

The input schema is empty, so the description's mention of 'message id' and the endpoint path /conversations/messages/{id} is the only signal that an identifier is required. This adds essential meaning beyond the schema, though the exact argument name and type are not specified.

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

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

The description states a specific action and resource: 'Get message by message id' with a concrete GET endpoint and scope. This makes the tool's primary purpose clear and separates it from list-oriented siblings like conversations_get_messages, though it does not explicitly name any alternative tools.

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

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

The phrase 'by message id' implies the tool should be used when a single message identifier is available, but there is no explicit guidance about when not to use it or which sibling to prefer. No exclusions or alternative tool references are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context beyond annotations by specifying the auth token type ('Token: location') and required scope ('conversations/message.readonly'), as well as the endpoint format. It does not describe the response shape, but for a read-only GET this is a minor gap.

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

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

The description repeats the title almost verbatim before restating the same idea, creating redundancy. The endpoint and auth details are valuable, but the first sentence could be removed or merged. It is compact but not tightly edited.

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

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

For a simple two-string-param GET with read-only and idempotent annotations, the description covers the endpoint, token, and scopes. It does not specify the return format, but the absence of an output schema and the straightforward resource make this acceptable. The description could have noted that this is not the transcription endpoint, but that is reasonably inferable from the name.

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

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

Schema description coverage is 100%, so both messageId and locationId are already documented. The description only adds 'passing the message id' and shows locationId in the endpoint path, providing no additional semantic meaning. A baseline score of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states a specific action and resource: 'Get the recording for a message by passing the message id', and includes the exact endpoint path. This distinguishes it from siblings like conversations_get_message_transcription by the object type 'recording', even though it does not explicitly contrast with them. The opening duplicates the title but does not undermine purpose clarity.

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

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

No guidance is provided about when to use this tool versus alternatives such as conversations_get_message_transcription or conversations_download_message_transcription. It mentions required token and scopes, but gives no criteria, exclusions, or comparison to sibling tools. The only implied usage cue is the resource name 'recording'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destuctiveHint=false, so the safety profile is covered. The description adds the required OAuth scope 'conversations/message.readonly', which is useful authorization context, but does not disclose behavior such as default limit, pagination semantics, or result ordering.

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

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

The description is short and front-loaded, with the endpoint and scope appended compactly. It is not padded with fluff, though 'Get messages by conversation id' largely repeats the tool title and could have been replaced with more useful behavioral detail.

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

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

Together with the fully documented schema and safety annotations, this is adequate for a simple read-only listing tool, but it omits any description of response format or pagination behavior despite there being no output schema. Auth scope and endpoint are present, which helps, but richer list-specific context would improve completeness.

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

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

Schema description coverage is 100%, so parameters are already documented in the input schema. The tool description does not add extra meaning about conversationId, type, limit, or lastMessageId beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Get messages by conversation id', and the endpoint makes the operation concrete. It is distinguishable from the sibling conversations_get_message by the plural resource and path. However, it does not explicitly clarify that this returns a list or that optional filters are available.

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

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

The description provides no guidance on when to use this tool versus alternatives such as conversations_get_message, conversations_search_conversation, or conversations_export_messages_by_location. Sibling names imply differences, but the description itself leaves selection entirely to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds genuinely useful access context – the exact HTTP method, 'Token: location', and required scope 'conversations/message.readonly' – which the annotations do not convey.

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

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

The text is short but opens by repeating the title verbatim ('Get transcription by Message ID'), and the body is a run-on sentence. It packs route, token, and scope compactly, yet the redundancy makes it less crisp than it should be.

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

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

For a simple two-parameter read with strong annotations, the endpoint, token, and scope are effectively covered. The lack of an output schema means the description could have added what the response contains or whether it returns raw text, but this is a moderate gap rather than a fatal one.

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

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

Schema coverage is 100%: both required parameters are documented as strings, and the description reinforces locationId/messageId via the REST path. The description adds no format or additional semantics beyond the schema, so the baseline 3 applies.

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

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

The description names the exact action ('Get') and resource ('recording transcription for a message') and provides the full REST path, so intent is clear. It does not explicitly contrast with the sibling audio-recording and download-transcription tools, but the resource is unambiguous enough.

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

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

It implies the use case: pass a message ID to fetch its transcription, and includes the required token/scope. However, it gives no explicit guidance about when to prefer this over conversations_get_message_recording or conversations_download_message_transcription, leaving some selection ambiguity among sibling transcription tools.

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

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

Annotations already indicate a read-only, non-destructive, idempotent operation. The description adds that it returns a list with sort/filter options and specifies the endpoint and scopes. It doesn't contradict annotations and adds some context, but doesn't disclose pagination or rate limits.

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

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

The description is very concise, with the main purpose front-loaded in the first sentence, followed by endpoint and scopes. No redundant filler.

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

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

Given the tool's complexity (21 parameters, no output schema), the description is sparse. It doesn't mention pagination, defaults beyond what the schema notes, or any usage examples. Agents need more guidance on constructing searches, such as combining filters or using startAfterDate for pagination.

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

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

Schema descriptions cover 100% of parameters, so the description doesn't need to add parameter details. It doesn't add anything beyond what the schema provides; it relies entirely on the schema for parameter meaning.

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

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

The description clearly states the tool's function: searching conversations and returning a list matching criteria. It distinguishes from single-conversation retrieval by emphasizing 'list of all conversations' and includes the endpoint and scopes.

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention that for a single conversation by ID you should use get_conversation, or that for messages within a conversation you'd use get_messages. The description only states what it does, not when to choose it.

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

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

Annotations already indicate destructive and non-idempotent behavior, so the description adds useful context by noting that the same write/delete gates as dedicated tools apply and that all path/query/body fields are flattened. This goes beyond the structured annotations without contradicting them.

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

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

Two tight sentences with no filler. The core action and the critical flat-argument behavior are front-loaded, and the important gate caveat is appended efficiently.

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

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

For a highly generic dynamic endpoint tool, the description is reasonably complete: it explains the argument model, points to the schema-discovery sibling, and flags safety gates. It does not describe return values or error behavior, but those are inherently variable for 'any endpoint', so this is an acceptable gap.

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

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

Schema descriptions already cover the parameters at 100%, but the description adds meaningful semantics: arguments must be flat with path, query, and body fields at top level, and users should consult ghl_describe_endpoint for the exact shape. This materially improves an agent's ability to build correct calls.

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

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

The description clearly states the action ('Execute any endpoint by tool name') and the resource (any GHL endpoint), and immediately distinguishes itself from the dedicated sibling tools by being a generic executor. The mention of a flat arguments object further specifies how the operation is performed.

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

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

The description implies a generic fallback use case but never explicitly says when to prefer this tool over a dedicated sibling endpoint. It references ghl_describe_endpoint for input structure and mentions write/delete gates, but stops short of stating 'use dedicated tools when one exists' or providing a clear when/when-not rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds useful behavioral context by enumerating what the tool returns: input schema, required fields, auth scopes, and HTTP details. Potential error or formatting behavior is not described, but this is minor for a read-only introspection tool.

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

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

The description is a single focused sentence that front-loads the return payload and scopes the tool with 'for one endpoint by tool name.' There is no filler, repetition, or extraneous detail.

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

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

For a one-parameter, read-only introspection tool, this description covers what an agent needs: what the tool returns and how to identify the target endpoint. There is no output schema, so the listed return categories are sufficient, and missing error semantics are an acceptable gap at this complexity.

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

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

Schema coverage is 100%, and the schema already explains that 'name' is 'Tool name from ghl_search_endpoints.' The description repeats 'by tool name' but adds no new parameter semantics, so the baseline score of 3 is appropriate when the schema carries the semantic weight.

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

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

The description states a specific action ('Return') and a concrete object ('full input schema, required fields, auth scopes, and HTTP details for one endpoint'). It clearly distinguishes this introspection tool from sibling tools like ghl_search_endpoints and ghl_call_endpoint without requiring the reader to open the schema.

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

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

The description conveys a clear use case: obtain schema, auth, and HTTP details for a named endpoint. It does not explicitly name alternatives, but the parameter description 'Tool name from ghl_search_endpoints' gives workflow context, and the tool's meta-role is obvious from its name and siblings. No exclusions are stated, but the intended usage is clear.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds behavioral context beyond that: it searches across all 576 endpoints in 41 modules, includes endpoints not exposed as dedicated tools, and returns tool names intended for ghl_describe_endpoint / ghl_call_endpoint. It stops short of describing search matching semantics, but that is a minor gap given 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.

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

The core purpose and output are front-loaded in two efficient sentences. The long module list adds bulk but is genuinely useful as a reference for the module parameter and for understanding the tool's coverage. No filler or tautological phrasing is present.

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

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

For a search/discovery tool with no output schema, the description adequately explains the return value ('tool names') and how to chain it with ghl_describe_endpoint / ghl_call_endpoint. It also makes the scope explicit with the 576-endpoint/41-module framing. A more complete description might clarify how keyword matching works, but the schema and annotations fill most remaining gaps.

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

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

Schema coverage is 75%, with query, limit, and module already documented via descriptions and examples. The description adds useful parameter-related context by listing the valid module names and clarifying that the input is a keyword search returning tool names. The method parameter is an enum with obvious values, so no further description is essential.

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

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

The description states a specific action ('Find GoHighLevel API endpoints by keyword'), a concrete scope ('all 576 endpoints in 41 modules'), and the output ('Returns tool names'). This clearly distinguishes it from the data-specific sibling search tools and directly connects to the ghl_describe_endpoint / ghl_call_endpoint workflow.

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

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

The description indicates when this tool is valuable by noting it covers endpoints 'including ones not loaded as dedicated tools', implying discovery use when no dedicated tool exists. It also names the downstream tools to use with the results, giving a clear workflow. It does not explicitly say when not to use it or when a dedicated sibling search tool should be preferred, but the context is strong.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the description does not need to restate those traits. It adds the required auth scope ('locations/templates.readonly') and endpoint, but does not disclose default filtering behavior, pagination, deleted-template handling, or response shape.

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

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

The description is concise and front-loads the verb, resource, and endpoint in one sentence with no filler. The wording 'all or email/sms templates' is slightly ungrammatical and hurts clarity, but the overall structure is efficient.

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

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

Given strong read-only annotations, high schema coverage, and required parameters explicitly present in the schema, the description provides enough for an agent to select and invoke the tool. The lack of an output schema and response-format details is a minor gap, but the endpoint and resource name make the expected return type evident.

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

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

Schema description coverage is 83%, so the schema already documents skip, limit, type, deleted, originId, and locationId well enough. The description only loosely hints at email/sms filtering and adds no real semantic value beyond the enum and parameter names already present.

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

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

The description uses an explicit GET verb, names the resource (location templates), and gives the exact endpoint path, which helps distinguish it from other read-only sibling tools. However, the phrasing 'all or email/sms templates' is awkward and leaves whether 'all' is a distinct filter mode somewhat ambiguous.

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

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

No explicit when-to-use guidance or alternative exclusion is given. The resource 'templates' makes the intended use reasonably clear and no sibling tool covers the same endpoint, but the description does not state when to choose this over other locations or template-related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds only the endpoint path and provides no additional behavioral context such as single-resource semantics, response shape, or limitations. It does not go beyond what the annotations already communicate.

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

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

The description is one compact sentence with no filler and front-loads the HTTP method and endpoint. It is appropriately concise, though it is also too sparse to provide contextual guidance.

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

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

For a simple two-parameter read operation with rich annotations and complete schema coverage, the endpoint alone is nearly sufficient. The main gap is the lack of usage guidance to disambiguate it from the many sibling getter and list tools.

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

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

Schema description coverage is 100%, so the baseline applies. The schema documents id as 'Custom Field Id or Field Key' with examples and locationId as 'Location Id'; the description adds no parameter meaning beyond the path placeholders.

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

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

The description states a concrete verb and resource ('Get Custom Field') and includes the exact endpoint path, which identifies the operation as fetching one custom field rather than a list. However, it does not explicitly differentiate from sibling tools such as locations_get_custom_fields or locations_get_custom_value.

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

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

There is no guidance about when to use this tool instead of locations_get_custom_fields, locations_get_custom_value, or other related getter tools. The agent must infer usage from the name and endpoint alone.

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

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

The description adds the HTTP method (GET) and the required OAuth scope (locations/customFields.readonly), which are behaviorally useful beyond the annotations. The annotations already establish read-only, idempotent, non-destructive behavior, and the description is consistent with them. No contradiction found.

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

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

The description is compact and front-loaded: it starts with the operation, then provides the endpoint and auth scope. There is no redundant or filler content.

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

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

For a simple read-only GET with two parameters and strong annotations, the description is mostly sufficient. However, it does not explain what the returned custom fields contain or how this differs from the singular custom field endpoint, leaving a moderate gap for an agent deciding between related tools.

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

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

Schema description coverage is 100%, so the input schema already documents both locationId and model. The description does not add extra meaning about the model filter or locationId format, so it relies on the schema as expected.

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

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

The description clearly states the operation is 'Get Custom Fields' and includes the exact endpoint path with locationId. It is specific about the resource, though it does not explicitly distinguish itself from the sibling tool locations_get_custom_field beyond the plural/singular naming.

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

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

There is no guidance about when to use this tool versus alternatives such as locations_get_custom_field or locations_get_custom_values. The endpoint and scope are provided, but no context is given for choosing this tool over related custom-field tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the explicit HTTP GET method and the resource path template, which is useful contextual detail beyond the annotations. However, it discloses no further behavioral traits such as return format, auth requirements, or error behavior.

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

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

The description is extremely concise, front-loading the operation and endpoint in a single line with no filler. However, it is almost too sparse: it restates the title and adds the URL, but omits explanatory content that could aid tool selection. It is efficient but at the cost of completeness, warranting a 4 rather than a 5.

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

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

With no output schema, the description should explain what the tool returns or what a custom value is, but it does neither. There is also no mention of how this singular retrieval relates to locations_get_custom_values or custom fields. Given the low parameter count and annotations, the operation is simple, but the missing context about return values and resource meaning leaves a notable gap for an agent.

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

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

Schema description coverage is 100% for the two required parameters, so the baseline is 3. The description's endpoint template shows that locationId and id are path parameters, adding a small amount of locational meaning beyond the schema's 'Location Id' and 'Custom Value Id'. But it does not clarify value formats, constraints, or relationships beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Get Custom Value' with the endpoint GET /locations/{locationId}/customValues/{id}. This makes clear it retrieves a single custom value by ID, and the singular form distinguishes it from sibling locations_get_custom_values (plural). However, it does not explain what a 'custom value' semantically represents, so it is clear but slightly under-specified.

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

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

No usage guidance is provided. The description does not state when to use this tool versus the many sibling tools, such as locations_get_custom_values (list all) or locations_get_custom_field. An agent must infer from the endpoint and tool name that this is for retrieving one specific custom value by ID, which is left entirely to the reader.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the OAuth scope 'locations/customValues.readonly' and the explicit endpoint, which is useful authentication context, but it does not describe return format, array shape, pagination, or any other behavioral details. No contradiction with annotations.

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

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

The description is a single concise sentence containing the endpoint and scope with no filler. It is front-loaded and easy to parse, though it mostly restates the title and leaves room for more informative content.

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

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

For a simple read-only operation with one parameter and rich annotations, the schema and annotations cover much of the safety profile. However, the description does not explain what custom values are, whether multiple results are returned, or when to choose this over the singular locations_get_custom_value. With no output schema, these gaps are not filled elsewhere.

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

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

The input schema has 100% coverage for the only parameter, locationId, with the description 'Location Id'. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states the action 'Get' and the resource 'Custom Values', and includes the endpoint [GET /locations/{locationId}/customValues] and the required scope. This makes the operation clear, though it does not explicitly differentiate it from the similarly named sibling tool locations_get_custom_value.

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

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

The description provides no guidance on when to use this tool versus alternatives such as locations_get_custom_value (singular) or locations_get_custom_fields. Usage context must be inferred entirely from the tool name and endpoint.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond annotations by specifying the required token type and scope ('Token: location or agency. Scopes: locations.readonly.'), which is valuable for execution.

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

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

The description is short but contains noticeable redundancy: 'Get Sub-Account (Formerly Location)' appears twice in the same sentence. The endpoint and auth details are useful, but the repetition wastes a bit of space. Still, the key information is front-loaded.

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

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

For a simple one-parameter read operation with rich annotations and full schema coverage, the description provides enough to call the tool correctly. It includes the endpoint, token requirement, and scopes. Since there is no output schema, a brief mention of return details could be helpful, but the operation is straightforward enough that missing it is not a major gap.

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

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

Schema description coverage is 100% and the single parameter locationId is already described as 'Location Id'. The description adds only marginal context by referring to it as 'sub-account id', but this is largely redundant with the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get details') and resource ('Sub-Account (Formerly Location)') and explains the lookup mechanism: 'by passing the sub-account id'. It also includes the exact endpoint, which removes ambiguity and helps distinguish it from sibling tools like locations_search_locations.

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

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

The description clearly implies this tool is for fetching a single record when the sub-account id is already known. However, it does not explicitly state when not to use it or point to alternatives such as locations_search_locations for discovery, so usage guidance is only implied rather than fully articulated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds the HTTP method and required scope 'locations/tags.readonly' but does not disclose return format or pagination; given the strong annotations, this is a reasonable neutral score.

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

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

The description is very short and information-dense, with the endpoint and scopes included. Minor redundancy exists in the leading 'Get Tags Get Sub-Account...' phrase, but there is no wasted explanation.

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

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

For a simple one-parameter, read-only GET endpoint, the description supplies enough to invoke the call correctly: the path, the resource, and the required scope. It does not describe the response shape, but no output schema exists and the return value is strongly implied by the endpoint resource.

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

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

Schema description coverage is 100% and only describes 'Location Id', which is the baseline. The description adds value by showing the parameter in the endpoint path and clarifying that 'Location' now means 'Sub-Account', helping an agent supply the correct identifier.

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

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

The description makes clear the operation is retrieving tags ('Get Tags') for a sub-account/location, reinforced by the endpoint path '/locations/{locationId}/tags'. However, it does not explicitly differentiate itself from the sibling 'locations_get_tag_by_id' beyond the plural resource and path, so it is clear but not fully differentiated.

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

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

The intended usage is implied by the verb and resource: use this tool when you need the tags associated with a location/sub-account. There is no explicit when-to-use/when-not-to-use guidance or mention of alternatives such as 'locations_get_tag_by_id'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the GET method and path—no mention of response shape, error cases, permissions, or pagination.

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

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

The description is a single, front-loaded sentence with no filler. It includes the useful endpoint pattern without redundancy, making it easy to scan.

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

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

For a simple, idempotent GET with fully documented parameters and safe annotations, the description is mostly adequate. However, with no output schema and no description of what the response contains, an agent still has some uncertainty about what the tool returns.

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

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

Schema description coverage is 100% and both parameter descriptions are present, so the baseline is 3. The description's path template does clarify that id and locationId are path parameters, but it adds no deeper semantic meaning beyond the schema.

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

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

The description clearly identifies the action ('Get'), the resource ('Recurring Task'), and the lookup key ('By Id'), and the path template adds concrete routing detail. It does not explicitly contrast with sibling tools, but the recurring-task resource is distinct from the many other get-by-id siblings.

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

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

The description provides no explicit when-to-use guidance, prerequisites, or alternative tool suggestions. Usage is only implied by the tool name, which is not enough for an agent deciding among many similar getter tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the HTTP GET endpoint, which is minimal but not contradictory.

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

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

The description is very short and front-loaded with the action and resource. It includes the endpoint, which is useful, though the opening phrase largely repeats the tool title.

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

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

For a simple read-only singleton lookup with fully documented parameters and strong annotations, the description is sufficient. It does not describe the response shape, but the absence of an output schema and the simplicity of a GET-by-id operation make this a minor gap.

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

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

Schema description coverage is 100%, so both parameters are already documented with descriptions. The description reinforces the path parameters but adds no additional semantic meaning beyond the schema.

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

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

The description states a specific verb and resource ('Get tag by id') and provides the explicit endpoint path, making the operation clear. It distinguishes from sibling tools like locations_get_location_tags by indicating a single tag lookup, though it does not explicitly name alternatives.

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

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

The description implies usage when a specific tag ID and location ID are known, which is reasonably clear. However, it gives no explicit guidance on when not to use it or which sibling tool to prefer for listing tags or searching.

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

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

The description discloses the HTTP method (GET), the auth token location ('Token: location'), and the required scope ('locations.readonly'), going beyond the annotations. It is consistent with the readOnlyHint and idempotentHint, and does not hide the read-only nature. It does not describe return formatting or potential empty-result behavior, but the annotations already cover the 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.

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

The description is short and mostly efficient, but it opens with an unnecessary duplicate of the title: 'Fetch Timezones Fetch the available timezones.' That repetition wastes two words and makes the structure feel accidental rather than deliberately front-loaded. The endpoint and auth details are compact and useful.

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

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

For a simple read-only list tool, the description covers what it returns, the endpoint, and auth requirements. However, it references a path parameter, locationId, that is not present in the input schema, so an agent could be uncertain whether it must somehow supply that value or whether it comes from the token context. There is no output schema, and the return shape is only implied as a list of timezones.

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

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

There are zero declared parameters, so the baseline is 4. The endpoint path '/locations/{locationId}/timezones' does imply a location-scoped resource, adding context about what the result depends on. The description does not explain how locationId is supplied, but with no parameters in the schema this is not an immediate description failure.

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

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

The description clearly states the tool fetches available timezones, and the included endpoint specifies the resource path. It is distinguishable from all sibling tools, none of which target timezones. However, the opening repeats the title verbatim ('Fetch Timezones Fetch...'), which is redundant and slightly muddies the clarity.

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

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

The intended usage is implicit: call this tool when you need the list of timezones available for a location. There are no competing timezone tools among the siblings, so no alternative routing is necessary. It does not explicitly state when not to use it or provide prerequisites beyond the described token/scope.

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

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

Annotations already mark this as readOnly, openWorld, idempotent, and non-destructive, so the description does not need to restate those. It adds useful context by stating the HTTP method, token types, and required scope, but it does not disclose pagination or response behavior beyond what the schema defaults imply.

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

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

The description is compact and front-loaded: it names the resource, endpoint, HTTP method, token types, and required scope in one efficient line. Every piece of information earns its place, with no redundancy.

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

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

There is no output schema, yet the description never states what the search returns or how the optional parameters like email and companyId affect results. An agent can infer it lists matching locations, but the missing return-value and filter semantics leave an important gap.

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

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

Schema coverage is 80%, so the schema already documents skip, limit, order, and companyId. The description adds no parameter-specific meaning, but it also does not need to compensate for missing schema info, so the baseline 3 is appropriate.

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

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

The description identifies a specific action ('Search') on a specific resource ('Sub-Account (Formerly Location)') and provides a concrete endpoint, making the tool's purpose reasonably clear. It does not elaborate on exact search fields, but the resource is unambiguous and distinguishable from the many get_ tools in the sibling list.

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

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

No guidance is given on when to use this tool versus alternatives such as locations_get_location or other search endpoints. The only extra context is token and scope information, which is authentication info rather than usage direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the HTTP method (GET) and required scope (opportunities.readonly), which is useful context beyond the annotations. However, it does not disclose pagination behavior, list-vs-single return shape, or filtering semantics.

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

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

The description is very short, front-loads the endpoint and scope, and contains no filler. It loses a point because the brevity sacrifices substantive behavioral or semantic guidance, though as conciseness itself it is effective.

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

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

For a 7-parameter endpoint with no output schema, the description should at least indicate whether the tool returns a single record or a list, and what the results represent. It only says 'Get lost reason', leaving the result shape and usage context under-specified.

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

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

Schema description coverage is high at 86%, so most parameters are already documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description states a verb and resource ('Get lost reason') and adds the endpoint, so it is not a pure tautology. However, it does not clarify whether this returns a single lost reason or a paginated list, nor what a 'lost reason' represents, leaving the core purpose ambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as opportunities_search_opportunity or opportunities_get_opportunity. The endpoint and scope are given, but the agent must infer the intended use case entirely.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying the required OAuth scope ('opportunities.readonly') and the exact REST endpoint, which gives useful access context beyond the annotations. However, it does not describe return shape, error behavior, or pagination, so the added behavioral context is limited.

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

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

The description is a single sentence containing the HTTP method, path, and required scopes. No fluff or redundant content exists; every piece of information is useful for invoking the tool.

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

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

For a simple one-parameter read-only operation with full annotation coverage, this description is mostly complete: it gives the endpoint and the required scope. It does not describe the response format or potential 404 behavior, but the absence of an output schema and the simplicity of the operation makes those omissions acceptable.

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

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

The schema describes the only parameter 'id' as 'Opportunity Id', which is self-explanatory. Schema coverage is 100%, so the description does not need to add much; it also doesn't add any semantics beyond what the schema already provides. The endpoint path '{id}' reinforces that the id is the path parameter.

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

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

The description clearly states the action ('Get') and the resource ('Opportunity') and includes the exact endpoint path '[GET /opportunities/{id}]', so an agent knows what the tool does. It does not explicitly distinguish itself from sibling tools like opportunities_search_opportunity, but the get-versus-search contrast is evident from the name.

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

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

The description provides no guidance on when to use this tool versus alternatives such as opportunities_search_opportunity or opportunities_search_opportunities_advanced. There is no mention of prerequisites, filtering, or when a search would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the auth scope 'opportunities.readonly', which is useful context beyond annotations, but it does not describe response behavior, pagination, or any other side-effect-relevant details.

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

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

The description is compact and front-loads the core action and endpoint. The 'Scopes' line is useful and there is no filler, though the phrase 'Get Pipelines' partially duplicates the title without adding much information.

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

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

The tool is simple, but with no output schema and no parameter explanation, an agent lacks important calling context. The annotations cover safety but not what the response contains, how locationId should be sourced, or what makes this tool distinct among related opportunities tools.

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

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

Schema description coverage is 0%, and the description gives no meaning for the sole required parameter 'locationId'. While the parameter name is somewhat self-explanatory, the description contributes nothing to clarify what value should be passed or how it affects the request.

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

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

The description states a specific verb and resource ('Get Pipelines') and includes the HTTP endpoint and required scope, making the basic purpose unambiguous. It does not explicitly differentiate it from sibling opportunity tools, but 'pipelines' is a distinct resource among the listed siblings.

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

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

There is no guidance on when to use this tool versus the many sibling tools. It does not say 'use this to list pipelines before creating an opportunity' or when the alternatives like opportunities_search_opportunity would be more appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the REST endpoint (POST /opportunities/search) and required scope (opportunities.readonly), which are useful behavioral signals. However, it does not disclose pagination/searchAfter behavior, query syntax, or how additionalDetails affects results, so the added transparency beyond annotations is modest.

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

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

The main sentence is single and direct ('Search Opportunities based on combinations of advanced filters'), and the endpoint/scopes line is dense but relevant. It could be more structured, but it is not verbose and front-loads the action and resource.

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

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

Even with readOnly annotations, this tool has six required parameters, a nested additionalDetails object, and no output schema. The description provides none of the parameter semantics, searchAfter usage, or pagination logic needed to make a correct call, and instead defers to an external documentation link. It is not self-contained enough for an agent to invoke reliably.

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

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

Schema description coverage is only 17% (only locationId has a generic description), so the description carries the burden of explaining the six required parameters. It does not mention query, limit, page, searchAfter, or additionalDetails at all, leaving an agent with no understanding of their meaning or formats.

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

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

The description states a specific verb ('Search') and resource ('Opportunities'), and adds that it operates on 'combinations of advanced filters,' which suggests a more complex search than a basic one. However, it does not explicitly differentiate itself from the sibling tool opportunities_search_opportunity, so it is clear but not fully distinct.

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

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

The phrase 'based on combinations of advanced filters' implies this tool is for complex, multi-filter searches, which provides some implicit usage context. Yet the description does not explicitly state when to use this tool over opportunities_search_opportunity or other search endpoints, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the HTTP GET verb and the 'opportunities.readonly' scope, reinforcing the read-only nature and providing permission context. It does not mention pagination, result shape, or rate limits, but the annotation coverage lowers the burden on the description.

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

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

The description is a single terse sentence that front-loads the action and adds endpoint and scopes. It is appropriately concise, though the opening phrase 'Search Opportunity' is largely redundant with the title, which costs a small amount of efficiency.

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

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

This is a 20-parameter search endpoint with no output schema, so the description needs to convey more than the action and scopes. It does not state that location_id is required, explain the role of q or status/country filters, or clarify pagination behavior. Sibling differentiation is also missing, making the description incomplete for effective tool selection and invocation.

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

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

Schema description coverage is 75%, so the schema already explains most parameters. The description adds no parameter-level meaning; parameters like q, order, status, country, and assigned_to remain without additional context beyond the schema. This aligns with the baseline for high coverage where the schema carries the load.

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

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

The description states the verb 'Search' and the resource 'Opportunity' and includes the endpoint [GET /opportunities/search], making the basic operation clear. However, it does not differentiate this from the sibling opportunities_search_opportunities_advanced, leaving some ambiguity about which search endpoint should be used.

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

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

There is no guidance on when to use this tool versus alternatives like opportunities_search_opportunities_advanced or opportunities_get_opportunity. The description only includes scopes, which is not usage direction. No exclusions, conditions, or preference cues are provided.

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