eDesk MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description still adds a genuinely non-structured behavioral fact: the note is internal and never customer-visible, plus the underlying endpoint. It omits permission requirements and whether retries create duplicates (relevant given idempotentHint=false).

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?

A single tightly written sentence with the WRITE cue front-loaded. The trailing "POST /order-notes" is redundant for an agent that invokes the tool through MCP rather than raw HTTP, which is the only wasted token.

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 tool with full schema coverage, no output schema, and annotations that already carry the safety profile, the description covers what matters: what is created and who can see it. It stops short of stating auth needs or side effects on the parent order.

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% — both text (with length bounds) and sales_order_id (with positivity bound) are documented in the schema. The description adds no syntax, formatting, or content guidance 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?

Names a specific verb (add), resource (note), and target (a sales order), which separates it cleanly from the sibling edesk_add_ticket_note and from the read-only edesk_list_order_notes. The parenthetical "never sent to the customer" further pins down the artifact being created.

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: the phrase "internal note … never sent to the customer" hints this is for private annotation rather than customer-facing communication, but the description never states when to choose this over edesk_add_ticket_note, edesk_reply_to_ticket, or edesk_update_ticket. No prerequisites or exclusions are given.

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=false, destructiveHint=true, and idempotentHint=false; the description adds what the annotations cannot — that the note is internal-only and never customer-visible, plus the underlying route (POST /messages with type Note). It does not explain why destructiveHint is true or whether notes can be edited/removed later, which is a small remaining 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 short sentences plus a route hint; the 'WRITE' marker and the core purpose are front-loaded. The trailing 'POST /messages with type Note' is slightly implementation-flavored for an agent-facing description but is compact and adds precision, so it 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?

No output schema exists, but the tool only takes two fully-documented parameters and the annotations cover the safety profile, so an agent has what it needs. The only thin spot is the unexplained destructiveHint=true, which the description does not address.

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 (text with length bounds, ticket_id with positivity constraint), so the schema carries the load. The description adds no parameter-level detail such as the 20000-char cap or id format; 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+resource ('add an internal note to a ticket') and explicitly scopes it as team-only and never customer-facing, which separates it from sibling edesk_reply_to_ticket and from edesk_add_order_note. An agent can route correctly 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 line 'for the team only and is never sent to the customer' gives clear context for choosing this over a customer reply, and the 'WRITE' prefix signals a mutation path. It stops short of explicitly naming the alternative tool or stating 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the shape of the response (body, direction, type, author, attachments) in the absence of an output schema, which helps the agent know what it will receive.

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?

A single front-loaded sentence plus the REST endpoint; every clause earns its place by enumerating returned fields and clarifying the Message/Note distinction. 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 reasonably compensates by listing the returned fields, and the single parameter is fully documented. Only the absence of explicit routing guidance relative to sibling read tools leaves 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 coverage is 100% for the single parameter, so the baseline applies, but the description adds provenance the schema lacks: the id comes from a ticket's message ids and identifies either a Message or a Note. That is meaningful semantic context beyond 'eDesk message id.'

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 ... message or internal note by id') and enumerates the returned content (body, direction, type, author, attachments). It clarifies the message/note duality, which is genuinely distinguishing information, though it does not explicitly contrast itself with sibling readers like edesk_get_ticket.

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 'from a ticket's message ids' implies the id must first be obtained from a ticket, which is useful implicit guidance. However, there is no explicit when-to-use statement or named alternative (e.g., edesk_get_ticket for the parent thread), so the guidance remains inferred rather than 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, and the description still adds real value by disclosing what payload comes back — items, amounts, ship-to/bill-to, tracking codes, delivery dates, ticket id, note ids. With no output schema, that inventory is the only source of return-shape knowledge. It does not mention behavior for a non-existent or unauthorized id.

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 covering scope and returned content, plus a compact endpoint reference. No filler, and the most important information (one order, by id) leads.

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 single-parameter read tool with annotations carrying the safety profile and no output schema, the description supplies the essential missing piece — the shape of the returned record. Only edge-case behavior (invalid/missing id, error response) is absent, which is 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 single parameter is fully documented in the schema (type, range, meaning), so the baseline of 3 applies. The description's 'by id' adds only a restatement of the key's role, not new format or provenance detail.

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

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

States a specific verb+resource (fetch one sales order by id) and enumerates the payload's contents, which clearly sets it apart from the list-style siblings. It never names edesk_list_sales_orders as the alternative, but the word 'One' plus the by-id scoping leaves no ambiguity about what this returns.

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: the by-id framing tells an agent to use this when it already has a specific sales_order_id, but there is no explicit 'use X instead when...' routing against edesk_list_sales_orders, and no stated prerequisite about where the id comes from (though the schema notes it is the sales_order_id on a ticket).

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, destructiveHint=false, and openWorldHint=true, so safety is covered structurally. The description adds only the REST path 'GET /templates/{id}', which conveys no error behavior (e.g., unknown id), auth requirements, or rate limits — so it adds little beyond the annotations.

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

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

Two short fragments with the key information (single template, keyed by id) front-loaded; nothing is padded. The trailing REST path is mildly redundant with the annotations' read-only signal but costs almost nothing.

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 single-parameter read with no output schema, the description is minimally sufficient — an agent knows it gets one template. It never says what the returned template contains or whether a missing id errors, leaving modest 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% and the single parameter template_id is documented in the schema with type and range constraints. The description adds no format or syntax detail beyond 'by id', 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 (get) and resource (one reply template) scoped by id, so an agent knows exactly what it retrieves. It does not differentiate itself from the sibling edesk_list_templates, which is the obvious near-neighbor.

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 when-to-use guidance and no mention of alternatives such as edesk_list_templates. The phrase 'by id' weakly implies a single-record lookup versus a listing, but nothing is stated explicitly.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the response shape — notably that messages come back only as ids, not bodies — which prevents a wrong assumption after the 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?

A single front-loaded sentence that carries the payload, with the sibling hand-off at the end. The trailing 'GET /tickets/{id}.' restates what the name and path-level context already imply, so it is one mildly redundant fragment rather than a flaw.

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 previews the returned fields and flags that message bodies require a second call. It stops short of noting behavior on an unknown/expired id or whether custom fields are expanded, which for a simple read is a minor omission.

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 with 100% schema description coverage ('eDesk ticket id.', positive integer), so the schema already does the work. The description's 'by id' adds no syntax, format, or sourcing detail beyond what is structured.

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 ('One ticket by id') and enumerates exactly what comes back: status, owner, tags, custom fields, linked sales order, message ids. This clearly separates it from edesk_list_tickets and the narrower edesk_get_message in the sibling set.

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?

Explicitly routes the agent onward for message content ('read each with edesk_get_message'), which is genuine when-to-use guidance for a follow-up call. It does not, however, state when to prefer this over edesk_list_tickets or how to obtain the id in the first place.

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, openWorldHint=true, destructiveHint=false), and the description adds the transport detail (GET /channels) plus a full list of returned fields (id, type, name, country, currency) — valuable since there is no output schema. It stops short of describing pagination limits 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?

Three short sentences, no filler, and the resource identity plus the motivating use case are front-loaded ahead of the endpoint 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 correctly compensates by naming the fields returned and the id-filtering use case, and pagination is handled by the schema. Only minor gaps remain, such as whether the list is paginated in practice or how many channels typically return.

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

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

Schema description coverage is 100% and both parameters (page, items_per_page) are fully documented in the schema, including the next_page chaining instruction. The description adds nothing about pagination, 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?

States a specific verb ('List') and resource ('sales channels connected to eDesk') and enumerates the channel types and returned fields, so an agent can distinguish it from sibling list tools like edesk_list_contacts or edesk_list_tags 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?

'Use the ids to filter tickets and orders' gives downstream context for the returned values, but it never says when to call this tool versus a sibling, nor does it mention pagination behavior (next_page is only hinted at in the param schema). Usage is implied rather than guided.

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=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it names the response fields (id, channel, full name, email, phone) and the underlying GET /contacts endpoint. It omits any note on result caps or pagination behavior, keeping it short of a 5.

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: capability first, then return shape and endpoint. Zero padding and nothing important buried.

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 compensates by listing the returned fields, and annotations carry the safety profile while the schema handles pagination and limits. It is nearly sufficient; only the interaction between the free-text 'query' and the specific filters is left unstated.

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 every parameter is already documented in the schema with types and bounds. The description only restates the filter categories and adds nothing on semantics (e.g. whether filters AND together, or how query differs from the field-specific filters). Baseline 3 is correct.

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 concrete verb plus resource: search the helpdesk's contacts/customers, and even enumerates the fields returned. This cleanly separates it from the sibling list_* tools (tickets, users, channels, tags), though it uses 'search' where the name says 'list', a minor wobble.

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 usage by naming the filter dimensions (free text, email, name, phone, consumer id), which tells the agent this is the lookup entry point for contacts. It gives no when-not guidance, no mention of combining filters, and no references to related tools, so usage is only implied.

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, destructiveHint=false and openWorldHint=true, so the safety and reach profile is covered externally. The description adds only the returned field list and the underlying endpoint (GET /order-notes), with no pagination behavior, ordering, or volume/cost caveats beyond what the schema states.

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 purpose and scope lead, the returned fields follow in parentheses, and the endpoint is a compact footnote. Nothing 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?

With no output schema, the parenthetical field list (id, sales order id, author, text, attachments) usefully describes the shape of the response, and pagination is fully specified in the schema. What remains thin is guidance on ordering or whether every order always has notes.

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 (page, items_per_page) already carry defaults, bounds, and the 'pass the previous reply's next_page' hint. The description contributes nothing extra about parameters, 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 ('List the internal notes attached to sales orders') and enumerates the returned fields, so the agent knows exactly what comes back. It scopes to sales orders rather than tickets, which implicitly separates it from edesk_add_ticket_note, but it never names a sibling or an alternative read path.

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 resource name: read this when you need the notes on an order. There is no explicit when/when-not guidance and no pointer to edesk_add_order_note for creating a note or edesk_list_sales_orders for first resolving an order 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds the returned-field set and the underlying endpoint (GET /sales-orders), but says nothing about result size, pagination traversal, permissions, or rate limits beyond what the schema implies.

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 that lead with purpose then filters, with no filler. The trailing 'GET /sales-orders' fragment is minor and slightly redundant with the tool name, but overall the text is tight and 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?

With 14 optional params and no output schema, the description usefully names the fields returned and the filtering surface, which is what an agent needs to invoke it. It still omits the pagination loop (page/next_page) and the fact that all filters are optional, but those are covered by the schema.

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 each of the 14 parameters is already documented in the schema, so baseline is 3. The description's filter enumeration ('status, channel, contact, marketplace order id, id range and created/updated dates') is largely a restatement of schema fields rather than added semantics.

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

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

Specific verb+resource ('List the marketplace/store orders that eDesk holds') with the returned fields spelled out (status, items, amounts, addresses, tracking codes, linked ticket id). This clearly separates it from the singular edesk_get_sales_order and from the other edesk_list_* tools.

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

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

The description says what can be filtered but never says when to choose this tool over edesk_get_sales_order (known id) or how it relates to edesk_list_tickets. No prerequisites, pagination workflow, or exclusions are stated — the filter list is parameter detail more than usage 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the HTTP endpoint (GET /tag-groups); it does not disclose pagination behavior, throttling, or authentication requirements beyond what the schema and 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 front-loaded sentence plus a short endpoint reference. Every word earns its place, and there is no filler or redundancy.

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

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

For a simple read-only list endpoint with clear annotations and fully described pagination parameters, the description is largely sufficient. The only minor gap is that no output schema exists, so the description does not describe the shape of returned tag-group records.

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 pagination parameters are fully documented in the schema itself. The description adds no parameter-level detail, so the baseline of 3 is appropriate when the schema does all 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 gives a specific verb (List), a precise resource (tag groups), and clarifies the domain relationship (tag groups that organize ticket tags). This is enough to distinguish it from the sibling tool edesk_list_tags 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 name and description: use this to retrieve tag groups. However, it never explicitly states when to prefer this over listing tags or other related tools, nor does it mention any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the shape of the returned records (id, name, color, active flag, tag group id), which the agent could not learn from annotations alone. It does not mention pagination behavior or auth requirements, which the schema partly covers.

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 filler, and the core purpose plus returned fields are front-loaded ahead of the integration hint. Every clause 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?

With no output schema, the description compensates by enumerating the returned fields, and pagination is fully handled in the schema. For a simple read-only list tool this is nearly complete; only the relationship to the tag-groups listing sibling is left implicit.

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% — both pagination parameters (page, items_per_page) are fully documented in the schema, including the 'pass the previous reply's next_page' hint. The description adds no parameter-level detail 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+resource ('List ticket tags') and enumerates the returned fields (id, name, color, active flag, tag group id), plus the endpoint GET /tags. It does not explicitly distinguish itself from the sibling edesk_list_tag_groups, which is the nearest alternative, 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?

The sentence 'Use the ids in edesk_update_ticket (tag_ids)' tells the agent what to do with the results, which is useful downstream routing, but it never states when to call this tool versus edesk_list_tag_groups or any other listing tool. Usage is implied rather than spelled out.

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 and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the returned field set (id, name, subject, body text, channels, usage) and the backing endpoint GET /templates, which matters because there is no output schema.

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

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

A single sentence front-loads the action and resource, then packs the return fields and endpoint into a compact parenthetical. No filler, nothing restated from the annotations.

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 with full schema coverage, the description is nearly sufficient: it names the resource, the returned fields, and the endpoint. Pagination mechanics are handled by the schema, so nothing critical is missing, though a note on result ordering or default filtering would round it out.

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 page and items_per_page are fully documented there including defaults and the next_page chaining pattern. The description adds nothing about parameters, so the baseline 3 for schema-heavy definitions 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?

States a specific verb (List) and resource (saved reply templates), and enumerates the fields the agent will get back, which separates it from the sibling edesk_get_template. It never names that sibling explicitly, so differentiation relies on the tool name rather than the description.

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 says what the tool returns but gives no guidance on when to use it versus edesk_get_template, nor any prerequisites. The only usage hint, pagination chaining via next_page, lives in the schema, not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the bar is lower. The description adds genuine value by enumerating the response payload (subject, type, status, message ids, reply count, AI classification) in the absence of an output schema. It says nothing about pagination behavior, result caps, or ordering semantics beyond the schema, so it only partially enriches 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?

Two sentences, front-loaded with the core action before the filter enumeration, and the 'GET /tickets' endpoint tag is a useful anchor. The middle sentence is a long comma-separated run that partly duplicates schema field names, which slightly dilutes the economy.

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 13 optional parameters, no output schema and no required inputs, the description does the important extra work of listing the returned fields, which an agent needs for planning. Combined with annotations covering read-only safety, the picture is nearly complete; only pagination/ordering behavior is left to the schema.

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 all 13 parameters documented including enums, formats and defaults, so the baseline is 3. The description's filter list largely restates what the schema already states ('Filter by status, type, channel...'), adding no syntax or edge-case detail. It does hint at the seller-order-id meaning ('marketplace order id'), but that is already in the schema.

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

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

The description opens with a specific verb and resource ('List support tickets from all channels') and enumerates the returned fields, so its scope is unambiguous. Against the sibling set it is clearly the ticket-collection reader, distinct from edesk_get_ticket (single ticket) and the other edesk_list_* tools (different resources). No ambiguity about what an agent gets back.

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 names the eight filter dimensions ('Filter by status, type, channel, contact, owner, sales order, seller order id and last-updated date'), which implies how the tool is meant to be used. However, it never states when to reach for this versus edesk_get_ticket or how it relates to siblings, and gives no exclusions or prerequisites. Usage is implied, not guided.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the note that returned ids map to ticket owners and discloses the returned fields, but says nothing about pagination behavior despite a paginated endpoint.

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 compact sentences, front-loaded with what is listed and what fields come back, followed by the usage note and endpoint. No filler, though the trailing 'GET /users' is somewhat redundant given the tool name.

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 listing tool with fully documented parameters and annotations carrying the safety profile, the description is adequate. It nonetheless omits pagination behavior and return-shape detail (no output schema), which is the main remaining 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 both parameters (page, items_per_page) are fully documented in the schema, so the description needs to add little. It contributes no additional parameter meaning, which is acceptable at baseline 3 given complete schema documentation.

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

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

Specific verb+resource ('List the eDesk users (support agents)'), names the fields returned, and grounds it with an endpoint. Clearly distinct from sibling listers like list_contacts or list_tickets by naming the resource 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?

Adds one genuine usage hint: 'Use the ids as ticket owners,' which tells the agent why to call this (to obtain owner ids for tickets). But it gives no when-not-to-use or alternative-sibling guidance; it's implied rather than explicit.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description adds far more: the reply cannot be recalled once queued, the audience is determined by the channel's default recipients setting, and a failed-in-transit call may still have queued the reply so the ticket must be checked before retrying. This is exactly the context an agent needs before an irreversible customer-facing write.

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?

Front-loads the critical warning (WRITE, CUSTOMER-VISIBLE) and every sentence carries operational weight. It is somewhat dense and could be tightened, but there is 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 and only three simple params, the description covers what an agent must know: irreversibility, audience resolution, the approval gate, the alternative tool, and retry semantics after an ambiguous failure. Nothing essential 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?

Schema description coverage is 100%, so ticket_id, text and subject are already documented in the schema. The description adds semantic context about audience/recipients that the schema does not, but says nothing about subject usage or the 20000-char text limit, 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?

Opens with a specific verb and resource ("send a reply on a ticket") and explicitly scopes it as WRITE, CUSTOMER-VISIBLE. It differentiates from the nearest sibling by routing internal notes to edesk_add_ticket_note, and mentions the underlying POST /messages with type Message.

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?

Names a hard precondition ("Only call this when the user has approved the exact text and audience"), an explicit alternative (edesk_add_ticket_note for internal notes), and a when-not case (use the eDesk reply box when recipients matter, since this API cannot choose them).

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 flag destructiveHint and idempotentHint, but the description adds material behavior: partial-send semantics ('only the fields you pass are sent') and the replace-not-merge danger of tag_ids, which is exactly the kind of footgun an agent needs. It stops short of mentioning permissions 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?

Four tight sentences, front-loaded with the WRITE marker and effect, with the highest-risk caveat (tag_ids replacement) placed before the endpoint reference. 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 annotations covering safety hints, 100% schema coverage and no output schema, the description supplies the missing operational context (partial update, tag replacement, no customer notification). Only auth/error expectations are absent, which is 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 coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining the replacement semantics of tag_ids and the read-first workflow needed to preserve existing tags. It adds no detail for status or subject, but those are already fully documented in the schema.

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

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

Opens with an explicit WRITE label, a concrete verb (change) and the resource (ticket), then enumerates the mutable fields. An agent can distinguish it from edesk_get_ticket or edesk_reply_to_ticket 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?

Gives a real prerequisite ('read the ticket first') for the tag_ids case and implicitly routes to edesk_get_ticket/edesk_list_tags via the referenced field names. It also clarifies scope versus reply_to_ticket ('Nothing is sent to the customer'), though it never states when-not to use this tool.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the exact identity fields returned and the concrete HTTP endpoint, which meaningfully orients the agent about the call's behavior.

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

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

One front-loaded sentence naming the subject and its returned fields, followed by the endpoint. No filler, nothing buried.

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's enumeration of returned fields (id, name, email, username, role, active flag) carries the return-value burden effectively. For a zero-parameter, read-only identity tool, nothing an agent needs 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 tool takes zero parameters, which is the baseline-4 case. Nothing in the description misrepresents the parameter surface.

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?

Names a specific resource (the eDesk user the API token belongs to) and enumerates the returned fields, plus the underlying GET /whoami endpoint. It is distinguishable from the sibling edesk_list_users by the singular, token-scoped framing, though it never explicitly contrasts them.

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 for resolving the current authenticated identity, but the description states no explicit when-to-use condition and names no alternatives it should be preferred over (e.g., edesk_list_users).

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