Gladly MCP by usefulapi

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

With only destructiveHint=true available, the description adds real behavioral context: the note is invisible to the customer, and the operation is non-idempotent (each call appends rather than upserts), which is exactly why a destructive/non-idempotent hint applies. It does not cover auth requirements, error modes, or what is returned.

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?

Three short sentences, front-loaded with the operation type and scoping caveat; the endpoint is a bonus for traceability. Nothing is repeated from the name/title verbatim and no sentence is 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 two-parameter write with no output schema and sparse annotations, the description covers what an agent needs: it's a write, it's non-idempotent, and the note is internal. Only missing piece is whether a note id or confirmation is returned, which matters slightly since no output schema exists.

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 both parameters documented in the schema, so the baseline is 3. The description adds nothing param-specific beyond the schema — it does not clarify body formatting (the schema already says 'Plain text') or what forms conversation_id can take.

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 opening token 'WRITE:' plus 'add an internal note to a conversation' gives a specific verb and resource, and the description immediately distinguishes visibility ('for agents only; the customer does not see it'). All siblings in the list are read tools, so the write nature is disambiguated up front.

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 states a clear conditional rule: 'Each call adds a NEW note, so do not repeat a call that succeeded,' which tells the agent when a retry is unsafe. It also implies the audience constraint that distinguishes this from a customer-facing reply, but it never names an explicit alternative tool or precondition (e.g., permissions).

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, so safety is covered. The description adds real behavioral detail beyond that: a hard cap of 50 returned profiles and ordering by newest update first. It stops short of stating what happens on no match or whether results can be paged.

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?

Three short sentences, zero filler, with the identifier requirement and result limits front-loaded. Every sentence carries information an agent needs.

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 partially compensates by describing result count and sort order. It is nearly complete for a simple lookup, though it omits behavior on zero results and any pagination or truncation semantics for the 50-cap.

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

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

With 100% schema description coverage, the params are already documented, including the E.164 example and the 'older Lookup Adaptors' caveat. The description's only added value is the cross-parameter mutual-exclusivity constraint, which is notable but largely mirrors schema text otherwise.

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 and resource ('Find customer profiles') plus the lookup keys, so the agent knows it is an identifier-based lookup rather than a list. It does not distinguish itself from the sibling gladly_get_customer, leaving ambiguity about which of the two retrieves a profile.

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 'EXACTLY ONE identifier' rule is genuinely useful call guidance, especially since the schema marks all three params optional and enforces no oneOf. However, it gives no when-to-use versus gladly_get_customer or gladly_list_customer_conversations, so routing between siblings is left to inference.

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

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

The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds the REST endpoint, but it does not disclose not-found behavior, permissions, rate limits, or anything else beyond the annotation.

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

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

The description is two compact sentences with no wasted language. The core lookup behavior is front-loaded, followed by a useful endpoint reference.

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 tool with full schema coverage and readOnly annotations, the description is largely complete. Return-value details are not described, but the low complexity makes that 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%, and the schema already explains that agent_id comes from gladly_list_agents. The description only restates that it is an id lookup, 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 a specific verb and resource: retrieve one agent profile by id. This clearly distinguishes it from the list_agents sibling, though it does not explicitly mention alternatives by 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 gives no explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. The id-only usage is implied but not explained.

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, so safety is covered; the description adds genuinely non-obvious behavior — that a merged conversation returns the surviving record — plus the underlying API endpoint. It omits what happens for missing/unauthorized ids, but the merged-conversation note is real value beyond structured fields.

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?

Three short clauses: purpose plus returned fields first, then the merged-conversation edge case, then the endpoint for reference. Every sentence earns its place 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?

With no output schema, the description usefully enumerates the metadata fields returned and flags the merged-conversation behavior, which is enough for correct invocation on a one-parameter read tool. It stops short of describing response shape or not-found handling, leaving a small residual 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% and the single parameter is already documented with its origin (gladly_list_customer_conversations), so the schema does the heavy lifting. The description adds no format or constraint detail about conversation_id beyond what the schema states; 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?

States a specific verb and resource ('Get the metadata of one conversation') and enumerates the returned fields (assignee, inbox, topics, custom attributes, status), which separates it from gladly_get_conversation_item and gladly_list_conversation_items by signaling metadata rather than message content. It never names a sibling explicitly, so differentiation is inferential rather than stated.

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 only implied: fetch a single conversation by id. There is no explicit guidance on when to prefer this over gladly_list_conversation_items or gladly_get_conversation_item, and no stated prerequisites or error conditions. The schema's parenthetical pointing to gladly_list_customer_conversations supplies part of the workflow, but not in the description.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the underlying endpoint (GET /api/v1/conversation-items/{itemId}). It says nothing about behavior on a missing/invalid id or what fields come back, so with annotations carrying the safety profile this is adequate but thin.

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 sentences, front-loaded with the action and resource, followed by the API mapping. No filler and nothing 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 one-parameter read tool with annotations and full schema coverage, the definition is callable. However, with no output schema, the description offers no indication of what a conversation item contains or how errors surface, leaving a real gap for an agent that needs to use the result.

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 single parameter already documents its provenance ('from gladly_list_conversation_items'). The description only restates 'by id' and adds no format or validation meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one conversation item') and enumerates the item types (message, email, note, call), which disambiguates the resource. It does not explicitly distinguish itself from gladly_list_conversation_items or gladly_get_conversation in the description body, so it stops short of a 5.

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

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

Usage is only implied: retrieve a single item when you have its id. There is no explicit when-to-use, no mention of using the list sibling to discover ids (that hint lives only in the schema), and no 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?

The readOnlyHint annotation already establishes this is a non-mutating read, so the description's burden is lower. It adds the returned field set and the underlying endpoint (GET /api/v1/customer-profiles/{customerId}), but says nothing about not-found behavior, empty custom attributes, or any rate/permission constraints that would help an agent interpret a failed call.

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 short sentences with the core action front-loaded and no filler. The trailing endpoint reference is somewhat redundant for an agent but is compact and can aid debugging.

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 tool with annotations covering the safety profile and no output schema, listing the returned fields gives the agent enough to know what comes back. Missing only edge-case behavior such as not-found handling, which is a minor 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 single parameter already documents its provenance ('from gladly_find_customers'), so the schema carries the semantics. The description only reinforces that lookup is by id and does not add format details or examples beyond what the schema states.

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 and resource ('Get one customer profile by id') and enumerates the fields returned (name, emails, phones, address, custom attributes). The 'by id' scoping implicitly separates it from the search-oriented gladly_find_customers, but the description never names that sibling to make the distinction 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?

Usage is only implied: an agent can infer this is the single-record lookup used when a customer id is already known. There is no explicit 'use this when…' guidance, no statement of what to do if the id is unknown (the schema, not the description, points at gladly_find_customers), and no note on alternatives.

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 the description is consistent with a pure read ('Get the metadata'). It adds the underlying endpoint, which helps an agent reason about the data source, but says nothing about what metadata is returned, error behavior for an unknown id, or auth requirements.

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

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

Two short sentences with no waste, and the purpose is front-loaded ahead of the endpoint reference. 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?

A simple single-parameter read whose safety profile is covered by readOnlyHint, so very little is required. The one remaining gap is that with no output schema, the description never indicates what 'metadata' comprises, though this is minor for such a narrow tool.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents inbox_id fully, including where to obtain it. The description's 'by id' adds no format or semantics beyond that; 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?

States a specific verb and resource with scope: 'Get the metadata of one inbox by id.' The 'one inbox' phrasing implicitly distinguishes it from the sibling list tool gladly_list_inboxes, and the concrete endpoint (GET /api/v1/inboxes/{inboxId}) reinforces the single-resource read. It stops just short of explicitly naming the list sibling as the 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?

Usage is implied by the framing — retrieve a single inbox when you already have its id — but there is no explicit when-to-use or when-not-to-use guidance, and the sibling gladly_list_inboxes is never mentioned in the description. The pointer to gladly_list_inboxes as the id source lives only in the schema's parameter description, not here.

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?

readOnlyHint=true already declares the safety profile, so the description doesn't need to re-assert it. It adds the backing endpoint (GET /api/v1/organization) and the exact return fields, but says nothing about auth requirements, caching, 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?

Two short sentences, zero waste, with the return payload front-loaded and the API endpoint trailing as supplementary 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?

With no output schema, the description helpfully enumerates the returned fields, which covers the main gap. It doesn't describe nesting or field types, so it falls just short of fully substituting for a return-value specification.

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 tool takes zero parameters, so the baseline is 4; there are no parameter semantics to explain and the description correctly omits any.

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 and resource ('Get metadata about the Gladly organization') and enumerates exactly which fields are returned (id, name, login domain, time zone, URL). This is clearly distinguishable from siblings like gladly_get_agent or gladly_get_customer, which target other 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?

Usage is implicit: this is the only tool that fetches org-level metadata, so an agent can infer it is the right call for organization settings. However, the description never states when to prefer it or what to do instead (e.g. use gladly_get_inbox for inbox-level settings).

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?

readOnlyHint=true already declares the safety profile, and the description adds useful detail beyond that: the exact fields returned and the HTTP route. It says nothing about permissions, not-found behavior, or rate limits, so it is solid 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?

Two short sentences, zero waste, with the core identity and return fields front-loaded before the API path.

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 tool with no output schema, listing the returned fields covers the main gap. Minor omissions are edge behavior (not-found, empty topics), which would be nice but are not essential to calling it correctly.

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

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

Schema coverage is 100% and the single task_id parameter is fully documented in the schema, including where to obtain it. The description's 'by id' adds no semantics beyond that, 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?

States a specific verb and resource ('Get one task by id') and enumerates the returned fields (body, assignee, due date, status, topics), plus the underlying endpoint. An agent can distinguish it from the sibling gladly_list_customer_tasks purely from this text.

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 'one task by id' phrasing and the schema note pointing to gladly_list_customer_tasks make the retrieval flow clear. It gives context for when to use it, but never states exclusions or what to do if the id is unknown.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It adds the returned field set and the REST endpoint, which is useful, but says nothing about result size, pagination, or rate limiting — the traits that matter for a full-collection listing call.

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 short sentences with zero waste — the capability and returned fields come first, the endpoint reference trails as supporting detail. Nothing is padded or repeated.

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 trivial zero-param read tool with readOnlyHint and no output schema, the description covers what it returns (id, name, email) and what it hits. The only meaningful omission is whether the full agent list is returned at once or truncated/paginated.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the empty schema is self-explanatory. Baseline 4 applies for a no-param 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?

States a specific verb and resource ('List the agents') and even enumerates the returned fields (id, name, email), plus the underlying endpoint. The 'list' vs 'get' distinction plausibly separates it from gladly_get_agent, though the description never names that sibling explicitly.

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 only implied: an agent can infer this is the tool for enumerating all agents rather than fetching one. There is no explicit guidance on when to prefer gladly_get_agent, no mention of whether the result is paginated or complete, and no prerequisites stated.

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 readOnlyHint annotation already establishes this is a safe read operation, so the description's main added value is the disclosed return shape (id, name) and the endpoint reference. It does not mention ordering, whether results are paginated or truncated, or any auth/rate-limit considerations.

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 short sentences: purpose and return shape first, API endpoint second. Every clause carries information and nothing is padded.

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 zero-parameter read tool, the description covers purpose, return fields, and the underlying endpoint, and the readOnlyHint annotation covers the safety profile. Only minor gaps remain (result ordering or size limits), which are low-risk here.

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 tool takes zero parameters, so the baseline is 4; the schema is an empty object and requires no explanation. The description correctly implies no inputs are needed, but adds nothing further because there is nothing further to add.

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 and resource ('List the audiences') and names the returned fields (id, name), so the agent knows exactly what comes back. Sibling tools cover different resources (agents, inboxes, topics), so there is no real ambiguity, though no explicit differentiation is offered.

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 only implied by the phrase 'used to target answers,' which hints at when an agent might need audience IDs (e.g., targeting a reply). There is no explicit when-to-use or when-not-to-use statement, and no alternative tool is 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?

readOnlyHint=true already declares the safety profile, so the description's added value is the ordering guarantee and the 1000-item ceiling, which tells the agent results may be truncated. That is genuine behavioral context beyond the annotations, though it stops short of saying how truncation is signalled or paged.

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 front-loaded sentence carrying the resource, item types, ordering and cap, followed by a short endpoint reference. The REST endpoint line adds little for an agent choosing a tool, but nothing is padded or 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?

There is no output schema, so the description carries the return-shape burden; it does name the item types and ordering, which helps. However, the explicit 1000-item cap implies truncation without explaining whether or how an agent retrieves the remainder, which is a meaningful gap for a listing tool.

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

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

Schema description coverage is 100%, so both conversation_id and session_id are already documented in the schema. The description adds no meaning beyond that — notably it never mentions the session_id filter or what a 'session' means in this timeline, so 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?

States a specific verb and resource ('List the timeline items of a conversation') and enumerates the item types returned (messages, emails, calls, notes), which distinguishes it from gladly_get_conversation_item and gladly_get_conversation without needing the schema. It does not explicitly name those siblings as alternatives, so it falls just short of a 5.

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

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

The ordering ('oldest first') and cap ('at most 1000') imply this is the bulk-read path for a conversation's history, but there is no explicit when-to-use guidance and no exclusion pointing to gladly_get_conversation_item for single-item fetches or gladly_get_conversation for metadata. Usage must be inferred from the sibling list.

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 safety profile (readOnlyHint=true), so the description's job is to add context — and it does: it discloses sort order, a hard cap of 100, and that truncation is signaled in the reply. It stops short of saying how to retrieve results beyond the cap, which is the one behavioral 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?

Two tight sentences: the first carries scope, ordering, cap and truncation semantics; the second carries return fields and the underlying endpoint. Nothing is redundant and the key constraints are 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 one-parameter read-only list tool with no output schema, this covers ordering, cap, truncation signaling, returned fields and the endpoint. The remaining gap is the absence of any guidance on paginating past the 100-item cutoff, which matters given the description explicitly raises that case.

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 is a single parameter with 100% schema description coverage, including where to obtain its value, so the schema does the work. The description adds no format or sourcing detail beyond what the schema already states; 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 a specific verb and resource (list conversations of one customer) and adds scope details — oldest first, at most 100 — that let an agent distinguish it from gladly_get_conversation and gladly_list_conversation_items without opening either 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?

Usage is implied by the single-customer scope and the schema note that customer_id comes from gladly_find_customers, which sketches a workflow. But the description never states when to prefer this over gladly_get_conversation or gladly_list_conversation_items, nor any preconditions 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 cover the safety profile (readOnlyHint=true), so credit goes to what the description adds: result ordering (newest first), a hard result cap of 2000, and an optional status filter. That cap is the most operationally important detail here, and it is disclosed concisely.

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 sentence plus one endpoint reference, both front-loaded with the behavior (ordering, cap, filter) ahead of implementation detail. 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 two-parameter read tool with full schema coverage and no output schema, the description covers ordering, truncation, and filtering, which is the meaningful behavioral surface. It does not explain how to page past the 2000 cap or what fields each task carries, though the latter is largely implied by the sibling gladly_get_task.

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 status enum is fully enumerated in the schema, so the description's 'optionally only OPEN or CLOSED' restates known information. Baseline 3 is appropriate; the description adds nothing new about customer_id format or id resolution.

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 and resource with an explicit scope constraint ('tasks of one customer'), which cleanly separates it from gladly_get_task (single task), gladly_list_customer_conversations, and the other list_* siblings. An agent can route to it without opening the schema.

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

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

The customer-scoped framing implies when the tool applies, and the status option hints at filtering, but it never states when to prefer gladly_get_task for a single task or what to do when a customer has more than 2000 tasks. Usage is inferable rather than declared.

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 `readOnlyHint: true` annotation already establishes that this is a safe read operation. The description adds the returned fields and the underlying API endpoint, but it does not disclose pagination behavior, rate limits, or whether all inboxes are returned.

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 two short sentences with no wasted words. The core purpose and returned fields are front-loaded, followed by the API endpoint as supporting 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 zero-parameter list tool with no output schema, the description provides enough context by naming the returned fields and the API endpoint. A minor gap is the absence of pagination or result-size details, but overall it is adequate.

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 parameters, so the baseline is 4. The schema is empty and fully described, and no additional parameter semantics are needed.

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: 'List the inboxes,' and specifies the returned fields (id, name, disabled state). It is clearly a listing operation, though it does not explicitly contrast itself with the sibling `gladly_get_inbox` for single-inbox 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?

Usage is implied by the tool name and simple list operation, but the description does not explicitly state when to use this tool versus `gladly_get_inbox` or any other alternative. No exclusions or prerequisites are provided.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the returned field set and the backing endpoint (GET /api/v1/topics), which is genuine added context, but it says nothing about volume, pagination, or whether disabled topics are included alongside active ones.

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?

Three short sentences, front-loaded with the purpose, then the use case, then the API mapping. Nothing is redundant and nothing needs to be re-read.

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 parameters and no output schema, the description carries the burden of describing the return shape, and it does list the four fields. It leaves open whether results are paginated or include disabled topics, which is the only meaningful remaining gap for such a simple tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description's parenthetical is about response fields rather than inputs, and it correctly conveys that no filtering arguments exist.

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?

Specific verb plus resource ("List the conversation topics") and it enumerates the returned fields (id, name, parentId, disabled), which no sibling list tool covers. An agent can immediately tell this apart from gladly_list_inboxes or gladly_list_audiences.

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?

Gives a concrete trigger: "Use it to turn the topicIds of a conversation into names," which tells the agent exactly when to call it. There are no competing siblings to exclude and no explicit when-not, so it stops just 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.