Desk365 MCP by usefulapi

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the endpoint path and the returned field set, but says nothing about behavior on a name miss (empty result vs. error) or any permission requirements.

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

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

A single front-loaded sentence with zero filler; the key constraint (exact name) and the payload contents are stated before the 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?

With one required parameter, no output schema, and no nesting, the description covers what is needed: the lookup key semantics and the returned fields stand in for a missing output schema. Only the not-found behavior 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 already carries 'Exact company name.', so the schema does the heavy lifting. The description's 'by exact name' merely reinforces the exact-match constraint rather than adding new syntax or format detail; 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 ('One company by exact name') and enumerates the fields returned (description, phone, address, SLA, domains, departments, custom fields). It implicitly distinguishes itself from desk365_list_companies via 'one' vs. 'list', but never names the sibling, so differentiation requires mild inference.

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

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

The phrase 'by exact name' tells the agent this is a lookup requiring an exact identifier rather than a search, which is useful selection signal, but there is no explicit when-to-use/when-not guidance or reference to list/search 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond that: the email precedence rule, the concrete field set returned, and the underlying endpoint (GET /v3/contacts/details). It omits what happens on a miss (empty result vs. error) and any auth expectations.

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 compact sentence front-loads the lookup key and follows with the returned fields; nothing is padded. The trailing endpoint reference is arguably redundant for an agent but is short and aids mapping to the API.

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 no output schema, listing the returned fields plus the endpoint makes it callable without guesswork. Only edge-case behavior on a missing contact is unspecified.

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 documents the precedence rule for secondary_email, so the description mostly restates it. Neither parameter is marked required, and the description does not clarify that at least one email must be supplied, which is the one semantic gap worth noting.

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 contact'), the lookup key (primary or fallback secondary email), and the fields returned (name, title, phones, company, departments, custom fields). This clearly separates it from the sibling desk365_list_contacts, which would be the multi-record 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?

Gives a concrete selection rule between its two parameters: use primary_email, and fall back to secondary_email only when the primary is unknown. It does not say what to do when the email is unknown entirely (e.g., use desk365_list_contacts to search by name), so the alternative routing is left implicit.

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 safety is covered; the description adds genuinely new behavior by enumerating the response payload (HTML and plain-text content, category, folder, author, views, likes) and decoding status (0 unpublished, 1 published). This matters because there is no output schema. It stops short of 5 by omitting what happens on a title miss or whether matching is case-sensitive.

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 dense sentence front-loads the identity of the resource, then the returned fields, then the endpoint. Every clause carries information; only the trailing 'GET /v3/kb/article/details' is arguably redundant for an agent that never issues raw HTTP.

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 is doing the right work by listing return fields and status encoding, and with readOnly annotations covering safety the remaining burden is low. The notable gap is failure behavior when no article matches the exact title, which an agent would want before calling.

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 already documents itself as 'Exact article title (from desk365_list_kb_articles)', so the baseline is 3. The description echoes 'exact title' but adds no new syntax, case-sensitivity, or length (300 char) guidance beyond the schema.

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

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

States a specific verb+resource ('Get knowledge base article') and narrows the identifier to 'its exact title,' which separates it from the sibling list tool desk365_list_kb_articles. It doesn't name the sibling explicitly, so it falls short of a 5, but an agent can tell what single record it fetches.

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

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

The phrase 'by its exact title' implies a precise-match lookup and steers away from partial/keyword retrieval, but the description never states when to use this versus desk365_list_kb_articles or what to do when the exact title is unknown. The schema's '(from desk365_list_kb_articles)' carries the routing hint rather than 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 and destructiveHint=false, so safety is covered by structured data. The description adds real value beyond that: it discloses the exact shape of the payload (SLA, due date, durations in minutes, custom fields, watchers) and pins it to GET /v3/tickets/details, which is meaningful for an agent with no output schema. It stops short of stating behavior for a missing/invalid ticket number.

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 field list is front-loaded and dense; the trailing endpoint reference is arguably filler for an agent but is only a few tokens. No sentence is redundant with the 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?

With no output schema, the enumerated return fields do most of the work an output spec would otherwise do, and annotations cover the safety profile. The remaining gap is error behavior for unknown ticket_number values, which a detail-fetch tool should mention.

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 ticket_number parameter, so the schema already carries the semantics. The description only echoes 'by its number' without adding format, range, or sourcing guidance, 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 resource ('one ticket by its number') and enumerates the fields returned, so the agent knows this is a full-detail single-ticket fetch. It does not distinguish itself from siblings like desk365_list_tickets, desk365_get_ticket_conversations, or desk365_search_tickets, so the agent must infer the boundary.

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 explicit when-to-use or when-not-to-use guidance and no named alternative. Nothing tells the agent that ticket_number must first be obtained via desk365_list_tickets/search_tickets, or that conversation content lives in desk365_get_ticket_conversations.

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 usefully enumerates what comes back (sender, recipients, bodies, attachments, timestamps) and what does not, but says nothing about pagination, volume limits or ordering behavior beyond the flag the schema already documents. Adds context, but modest given the annotation coverage.

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

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

Two dense, front-loaded sentences with no filler; the payload description leads and the scope caveat follows. The trailing 'GET /v3/tickets/conversations' is mild redundancy but is short and aids API-literate callers.

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 carries the return-shape burden and does so well by naming every message field returned. The main gap is absence of pagination/truncation guidance for what can be a long conversation thread on a 7-parameter 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 coverage is 100% and each include_* toggle plus newest_first is self-documented in the schema. The description's list of message types (customer replies, agent replies, private/public notes, forwards) loosely maps onto those filters but never explains the toggles themselves, so it adds no meaning beyond the schema. 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?

A specific verb+resource: retrieves the conversation (replies, notes, forwards) on a ticket, and explicitly distinguishes it from desk365_get_ticket by stating the original description lives there instead. An agent can tell the two apart 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?

The exclusion clause ('The original description is not included (it is on desk365_get_ticket)') gives a clear routing rule to the sibling. It implies the use case (reading the reply thread), but offers no explicit 'use this when you need the discussion history vs. the ticket fields' framing or other 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds only the HTTP endpoint GET /v3/time_entries/details, which is consistent but redundant; it does not disclose response shape, error behavior, permissions, or rate-limit context.

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 very short fragments, front-loaded and free of filler. However, the terseness borders on under-specification, so it does not reach a 5.

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

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

For a low-complexity single-record getter with full schema coverage and read-only annotations, this is nearly enough. It does not explain the returned object or error cases, and no output schema exists to cover that gap.

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

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

The sole parameter is fully described in the schema (100% coverage) as 'Time entry id (from desk365_list_time_entries).' The description adds no further meaning beyond 'by id', 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 names the resource (time entry) and the selector (by id), which distinguishes it from desk365_list_time_entries. It stops short of a full sentence such as 'Retrieves a single time entry,' but the intent is unambiguous.

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

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

Usage is only implied: 'by id' and the schema note that the id comes from desk365_list_time_entries suggest this should be used when an id is already known. There is no explicit when-to-use or when-not guidance and no alternative routing.

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 genuinely useful behavior beyond that: fixed page size of 30 and name-ordering of results, which an agent needs to plan paging. It does not state what happens at the end of the collection, 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?

One compact sentence that front-loads the action and resource, then supplies the two most operationally relevant facts (page size, sort order) and the endpoint. Nothing is wasted 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 simple, read-only, two-optional-parameter listing tool with full schema coverage and populated annotations, this covers what an agent needs to invoke it. The only real gap is termination/paging guidance ('stop when fewer than 30 returned'), which would make it fully self-sufficient.

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

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

Schema description coverage is 100%, so both offset and include_custom_fields are already well documented, establishing a baseline of 3. The description's page-size and sort-order context indirectly informs how offset behaves, but it adds no syntax or formatting detail beyond the schema.

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

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

States a specific verb and resource ('List companies') and clarifies the resource as 'customer organisations', which disambiguates it from contact and ticket listings. It does not explicitly contrast itself with desk365_get_company, but the list-vs-get verb separation makes the distinction reasonably clear.

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

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

Usage is implied by the verb 'List' and the endpoint note, and the '30 per call, sorted by name' detail hints that pagination is expected. However, there is no explicit when-to-use guidance, no mention of desk365_get_company as the single-record alternative, and no advice on how to page through results.

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 genuinely useful context beyond that: page size of 30 per call, default name-sorted order, and the exact endpoint GET /v3/contacts. It omits any note on total counts or rate limits, so it is not 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?

A single front-loaded sentence with the entity clarification, page size, default ordering, optional filter and endpoint in that order. No filler, nothing that fails to earn its place.

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

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

For a read-only paginated list tool with full schema coverage and rich annotations, the key calling facts (page size, offset-based paging, default sort, filter) are present. The lack of any hint about the returned record shape or how to detect the last page is a minor residual gap given there is no output 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%, so all five parameters are already documented, including the enums for order_by and order_type. The description only restates the default sort and the company filter, adding no new syntax or format meaning; 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 contacts') and disambiguates the entity with '(customers/requesters)', which an agent can map to tickets/requesters. It never names the sibling it is distinguished from (desk365_get_contact), so it stops short of full sibling-level differentiation.

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

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

The description implies bulk/paged retrieval with an optional single-company filter, which is enough to suggest when to use it over desk365_get_contact. It never states when NOT to use it or points to an alternative 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 the safety profile is covered. The description adds genuinely useful scope context — only article titles are returned and only live (non-archived) articles are included — plus the underlying endpoint GET /v3/kb/article/. It says nothing about pagination or expected result size, which matters for an 'all articles' listing.

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 front-load the return content, then the next step and endpoint. Nothing is wasteful, though the third fragment ('GET /v3/kb/article/.') is a bare endpoint reference of marginal value to an agent that cannot supply it as input.

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 input parameters and no output schema, the description carries the burden of explaining the return value, and it does so ('titles of all live articles'). The only real omission for a zero-arg list tool is pagination/result-cap behavior, which keeps it just below fully complete.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The description correctly implies no filtering is possible and that the call is unconditional.

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 ('The titles of all live knowledge base articles') and immediately distinguishes the scope from the sibling read tool by noting only titles are returned and that desk365_get_kb_article fetches the full article. An agent can pick between the list and get tools 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?

'Open one with desk365_get_kb_article' gives the explicit follow-up path and names the alternative tool, so the two-step list-then-fetch workflow is clear. It stops short of stating when not to use this tool (e.g. when the article ID is already known), so it lacks a full exclusion clause.

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, openWorldHint=true, so the safety profile is covered. The description still earns credit by adding non-annotation behavior: sort order (oldest reply first), page size (30 per call), and the underlying endpoint GET /v3/surveys/ratings — all directly useful for driving pagination.

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

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

One dense sentence with the type taxonomy, ordering, page size and endpoint, front-loaded with the resource. No filler, no repetition of the title.

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

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

For a read-only, single-optional-param list tool with no output schema, an agent has what it needs: what the ratings are, how they're ordered, the page size, and how to page. It stops short of saying what fields each rating contains or how to detect the last page, but those are minor given the tool's simplicity and annotations.

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 a single optional 'offset' parameter already documented in the schema, so the description carries no param burden. It adds nothing about offset semantics in the description, which is acceptable at this coverage level but is baseline, not value-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 the specific resource — customer satisfaction survey ratings — and decodes the type values (1 CSAT, 2 five-star, 3 NPS), so an agent knows exactly what data comes back. The list verb is only implied by '30 per call' and the title rather than stated outright, and no sibling differentiation is offered because none of the siblings overlap.

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

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

No explicit when-to-use or when-not-to-use guidance, and no alternative is named. Usage is only implied by the pagination hint ('oldest reply first, 30 per call'), which tells an agent how to page but not when this tool is the right choice over the ticket/contact siblings.

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 safety (readOnly, non-destructive, openWorld), so the description's contribution is return-shape and defaults: newest-first ordering, descriptions omitted unless include_description is set, the visible fields, and the underlying GET /v3/tickets endpoint. Pagination limit behavior beyond the offset param is not described.

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 tight sentences, front-loaded with the core action and scope, then filters, then the notable defaults. No filler; even the endpoint reference is compact and useful for 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?

With 19 optional params and no output schema, the description carries the burden well by enumerating returned fields, defaults and the "--" convention. It falls short on pagination semantics (how many total results, how to detect the last page) and on validation ranges for the 20-item list caps.

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, but the description adds meaning on top: the numeric priority scale (1 Low … 20 Urgent), the "--" sentinel for unassigned/empty, and the field list that helps map filters to readable output. It leaves order_by, ticket_count, updated_since and the include_* flags to the schema.

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

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

States a specific verb and resource ("List helpdesk tickets") and enumerates the fields returned, plus the default ordering (newest first). It does not distinguish itself from the sibling desk365_search_tickets, which an agent could easily confuse with this broad filter/list tool.

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 useful filter conventions, notably "Use '--' in a list to match unassigned/empty" and the include_description default. However it never says when to pick this over desk365_search_tickets or desk365_get_ticket, so the choice among 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?

readOnlyHint and destructiveHint=false already tell the agent this is a safe read, so the description's main added value is the endpoint and the field inventory. It says nothing about default ordering, page-size defaults (left to the schema), or how 'running timers' interacts with date filters — modest extra context beyond annotations.

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

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

Two sentences, front-loaded with the resource and field list, ending with the endpoint. No filler, though the parenthetical field enumeration is dense and slightly list-like rather than prioritized.

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

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

For a read-only, zero-required-parameter list endpoint with full schema documentation and no output schema, the description covers purpose, retrievable fields, filter axes, and the underlying route. Nothing an agent needs in order to call it correctly 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 every one of the 11 parameters is already documented with formats and defaults. The description only summarizes the filter groups (ticket, agent, company, billable, timers, dates) without adding semantics such as whether filters combine with AND or how created/started/updated differ.

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 logged time entries'), enumerates the returned fields, and names the filter dimensions, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with desk365_get_time_entry, but 'list' vs 'get' plus the plural scope makes the distinction inferable.

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 filter list implies when the tool is useful (by ticket, agent, company, billable, running timers, dates), but it never states when to prefer it over desk365_get_time_entry or desk365_list_tickets, nor any pagination/ordering expectations. 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: default field scope is only subject and ticket number, relevance is the default order, and archived tickets require an explicit search_in entry. It stops short of describing result payload shape or pagination limits beyond the offset parameter.

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 tight sentences with the core behavior front-loaded, then the scoping options, then the matching operators. No filler, no restatement of the tool name, and the endpoint reference is a compact trailing 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 100% schema coverage, no output schema, and read-only annotations, the remaining burden is search semantics, which the description handles well. The one gap is return shape: it does not say whether results include ticket IDs, snippets, or match counts, so an agent cannot anticipate what comes back beyond the include_description flag.

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, but the description adds search-syntax semantics the schema lacks entirely: double quotes force exact phrase matching and *text* matches within words. It also corrects the schema's claim that search_in defaults to "all supported fields" by stating the real default is subject and ticket number, which materially changes how an agent builds a query.

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 ("full-text search over tickets") plus the ranking model ("most relevant first"), which is enough to separate it from the sibling listing tool desk365_list_tickets. An agent knows immediately this is a relevance-ranked text query, not an enumeration.

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 tells you how to widen scope with search_in, which is real usage guidance, but it never names a condition for choosing this over desk365_list_tickets or desk365_get_ticket. The distinction is implied by "full-text search" rather than stated, leaving the agent to infer when an enumerated list is preferable.

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