Deskpro MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description earns its keep by explaining exactly what the destructive path is: is_note=false sends an email to the requester that 'cannot be unsent'. It also states the acting identity ('as the key's agent') and the underlying endpoint, going well beyond the annotation.

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

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

Front-loads the core action, then the two-branch mode semantics, then the irreversibility warning and endpoint. Dense and largely waste-free; the trailing API path is informational but not strictly needed for selection, keeping it short of perfect.

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 4-param mutation tool with no output schema and only a destructiveHint annotation, the description covers identity, mode semantics, and the irreversible side effect. It omits what the call returns and does not restate format defaults, but those gaps are minor given the schema documents them.

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 baseline is 3. The description adds consequence-level meaning for the required is_note parameter (emailed vs internal, irreversibility) that the schema's terse one-liner does not convey, pushing it above baseline.

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

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

States a specific verb and resource ('Add a message to a ticket') and immediately differentiates the two modes the single tool supports: internal note vs emailed reply. An agent can distinguish it from siblings like deskpro_update_ticket or deskpro_list_ticket_messages without opening any 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 clear mode-selection guidance via is_note=true vs false and the consequence of each. It does not compare against sibling tools (e.g., when to use update_ticket instead), but for a tool whose main ambiguity is note-vs-reply, the guidance is explicit and actionable.

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 supply destructiveHint=true, and the description adds a genuinely useful side effect: email domains auto-associate matching people. It stops short of stating permission/auth requirements, whether duplicate names are rejected, or what the call returns. The auto-association disclosure is real added value beyond the annotation.

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

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

Three short sentences with zero padding; the core purpose is front-loaded, followed by the key side effect and the endpoint. Nothing could be removed without losing information.

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

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

For a four-parameter create tool with full schema coverage and no output schema, the description covers purpose, the notable side effect, and the endpoint. It omits auth/permission needs and duplicate-handling behavior, which are the only meaningful gaps.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, which sets the baseline at 3. The description's note about email domains auto-associating people adds a bit of meaning about that parameter's effect, but gives no syntax, validation, or format 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 ('Create a customer organization') and even names the backing endpoint (POST /api/v2/organizations), so an agent immediately knows the operation. It does not explicitly contrast with siblings like deskpro_update_ticket, but the create-vs-get-vs-list distinction is unambiguous from the wording.

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 or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as deskpro_get_organization or deskpro_list_organizations. The email-domain note is a behavioral detail, not routing 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?

With only destructiveHint=true and a title in the annotations, the description carries most of the behavioral burden and does well: it discloses that Deskpro will auto-create the person when the email is new and that helpdesk triggers may send an email to the requester. Those side effects are not derivable from the schema or 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?

Three short sentences, front-loaded with the action and requester semantics; the trailing 'Deskpro: POST /api/v2/tickets.' is mildly redundant but costs little. No filler.

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

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

For a 13-parameter creation tool with no output schema, the description covers the essentials: it says it returns the created ticket, explains requester resolution, and warns about the email side effect. It does not mention authorization requirements or how assignment fields interact, but the schema handles those fields well.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value by explaining the person_id/person_email interplay and the resulting person-creation behavior, which the schema only gestures at with 'used when person_id is not given'.

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 ('Open a new ticket for a requester ... with a first message'), which cleanly distinguishes it from deskpro_add_ticket_message (adds a message to an existing ticket) and deskpro_update_ticket. The requester-identification parenthetical further pins down what kind of creation this is.

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

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

The description gives useful conditional guidance on how to identify the requester (person id vs. email), but never says when to use this tool versus sibling alternatives such as deskpro_add_ticket_message or deskpro_update_ticket, nor any prerequisites. Usage is implied by the verb, not stated.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the underlying GET endpoint and the fields returned, but does not disclose error behavior, permissions, or rate limits. It does not contradict the annotation.

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

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

The description is a single front-loaded sentence that states the purpose and returned fields, followed by a brief API reference. Every element is compact and there is no wasted text.

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-one tool with a fully documented parameter, readOnlyHint coverage, and no output schema, the description is complete enough. It names the returned fields, which compensates for the absent output schema, and no additional behavior is required for correct invocation.

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

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

Schema description coverage is 100%, so the single article_id parameter is already fully documented as 'The article's numeric id.' The description adds no syntax, format, or constraint details beyond what the schema provides, 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 ('Fetch') and resource ('a single knowledgebase article by id'), and lists the returned fields. This clearly distinguishes it from sibling tools like deskpro_list_articles and deskpro_search, which list or search rather than fetch one article by id.

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 id' implies the tool is used when an article id is known, but the description does not explicitly state when to use this tool versus deskpro_list_articles or deskpro_search. No exclusions or alternative-selection guidance is provided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds valuable behavioral detail beyond annotations by listing what the call returns (auth method, bound person id, profile) and framing it as a cheap credential check, which is helpful given the absence of an 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?

Two tightly written sentences plus a concise endpoint reference. Information is front-loaded with purpose and return contents first, then the usage note, then the HTTP mapping.

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, no output schema, and readOnlyHint already covering safety, the description supplies everything needed: what is returned, why to call it, and the underlying endpoint. No important gap remains.

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 has zero parameters, so there is nothing to document. The description appropriately does not attempt to explain parameters, and the baseline for no parameters is 4.

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 ('Return') and resource ('who the API key acts as'), and specifies the return contents (auth method, bound person id, profile). This distinguishes it from sibling tools like deskpro_get_person, which would fetch an arbitrary person rather than the authenticated identity.

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 clear context for use: 'A cheap way to confirm the helpdesk URL and key are right.' It does not name alternatives or state when not to use it, but the intended scenario is 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?

readOnlyHint=true already tells the agent this is a safe non-mutating fetch, so the description's added burden is light. It usefully names the fields returned (domains, labels, custom fields, ticket count) but says nothing about auth/scope requirements or error behavior for a missing 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?

Two tight sentences: the scope and payload come first, with the REST endpoint as a compact trailing reference. No filler and 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?

With no output schema, the description compensates by listing the payload fields an agent should expect, and the read-only annotation covers the safety profile. Only the include/side-loading semantics and any failure mode go unmentioned.

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 organization_id and include are already documented in the schema. The description adds no parameter-level detail and notably never mentions the include side-loading option, so it stays at the baseline.

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

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

States a specific verb and resource ('Fetch a single organization by id') and enumerates the returned fields, which clearly separates it from the list_organizations sibling via the 'single' scope. It stops short of naming the sibling it complements, so it falls just below the top band.

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 'by id' phrasing and the sibling set, but there is no explicit when-to-use versus when-not, no statement that deskpro_list_organizations should be used for browsing, and no prerequisites listed.

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, so safety is covered. The description adds genuine behavioral value by disclosing the shape of the result (name, emails, phones, organization, labels, custom fields, ticket count), which matters because there is no output schema. It still says nothing about permissions or error behavior (e.g., unknown 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?

Two sentences, front-loaded with the action and result contents. The trailing REST endpoint reference is mildly redundant with the tool name and of limited value to an agent, but it costs little.

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, enumerating returned fields is exactly the right compensation, and the schema fully documents the two inputs. Missing only edge-case behavior (not-found handling, whether `include` affects cost/size), which keeps it short of a 5.

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%, including the sibling-loading `include` parameter with examples, so the schema carries parameter meaning fully. The description only restates the id lookup and adds no syntax or constraint detail beyond it; 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 concrete verb+resource ("Fetch a single person by id") and enumerates the payload fields returned. The word "single" implicitly separates it from deskpro_list_people, but no sibling is named explicitly, so the differentiation is inferential rather than stated.

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

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

Usage is only implied: by requiring an id, the description suggests it is used when the id is already known, versus list_people or search. There is no explicit when-to-use, when-not-to-use, or alternative named, which is a real gap given three sibling read tools could plausibly be chosen instead.

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 readOnlyHint=true, so safety is already covered. The description adds a genuinely non-obvious behavioral trait beyond that: a merged ticket redirects to the ticket it was merged into, which an agent would otherwise not anticipate when interpreting the returned 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?

Front-loaded with the core action and returned fields in one tight sentence, followed by the merge caveat. The trailing 'Deskpro: GET /api/v2/tickets/{id}' is largely redundant with the name and id parameter, but it is compact and harmless.

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

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

With no output schema, the description usefully enumerates the returned fields and flags the merge redirect, which is the main edge case. The include parameter's side-loading behavior is left to the schema, which covers it adequately.

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

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

Schema description coverage is 100%, so both parameters (ticket_id and include) are already documented in the schema, including the include side-loading semantics. The description adds no parameter-level detail 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?

States a specific verb+resource+selector ('Fetch a single ticket by id') and enumerates the returned facets (subject, status, assignment, requester, labels, custom fields, SLA state and timing). This clearly distinguishes it from the sibling list_tickets, search, and list_organization_tickets tools.

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

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

The phrase 'by id' implies this is the single-record lookup versus the list/search siblings, but there is no explicit when-to-use or when-not-to-use guidance and no mention of the alternative path when only a search term is known. Usage is 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?

readOnlyHint=true already declares a safe read operation, so the safety profile is covered. The description usefully adds the shape of the returned payload and the underlying endpoint (GET /api/v2/agents), but says nothing about pagination behavior, default page size, or result ordering — the main behavioral gaps for a list 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?

One compact sentence plus a short endpoint reference; the resource, return fields, and purpose are front-loaded with zero filler. 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, listing the return fields is exactly the right compensation, and annotations carry the read-only safety profile. The only shortfall is that a caller wanting 'all agents' gets no hint that results are paged by default, which matters for a list tool used to pick an assignee.

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%: page, count, and the online tri-state filter (1/0/-1) are all documented in the schema itself. The description's mention of 'online state' loosely echoes the filter but adds no syntax, value semantics, or defaults beyond what the schema provides.

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

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

The description states a specific verb and resource ('List the helpdesk's agents') and enumerates the returned fields (id, name, email, online state), which cleanly distinguishes it from siblings like deskpro_list_people or deskpro_list_departments. An agent can identify what this tool returns 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?

'needed to assign a ticket' gives a concrete triggering context, which is more than most list tools offer. It stops short of naming when-not-to-use or an alternative (e.g., deskpro_search for finding a specific agent), so it isn't a full 5.

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

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

readOnlyHint=true already declares the safe-read nature, so the description's obligation is lighter, but it adds almost nothing beyond that and the schema — no pagination behavior, no defaults, no note on whether all articles or only published ones are returned. The GET endpoint reference is a minor addition.

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 compact sentences, scoping information front-loaded and no wasted prose. It is efficient, though the endpoint-only trailing clause adds little agent value.

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

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

There is no output schema, so return shape is unstated, and the description never mentions pagination despite page/count parameters. Adequate for a simple read-only list given full schema coverage, but with clear gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description names only three of the six filters (category, status, author) and omits page, count, and order_by, so it adds little beyond what the schema already fully documents.

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 (knowledgebase articles) plus the supported filters, so it is clearly distinguishable from the singular deskpro_get_article sibling. It stops short of explicitly naming and contrasting siblings, keeping it at a solid 4 rather than 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?

Implies the tool is for enumerating articles and mentions filterable dimensions, but gives no explicit when-to-use/when-not guidance and never contrasts itself with deskpro_search or deskpro_get_article. Usage is only inferable.

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

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

The readOnlyHint annotation already establishes the safety profile, so the description only needs to add extra context. It usefully discloses the shape of each department record, but says nothing about pagination behavior, result ordering, or whether the list is complete across parents — the main operational unknowns for a listing call.

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

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

One sentence, front-loaded with the purpose and followed by the returned fields and endpoint. Every clause carries information; nothing is redundant with 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?

With no output schema, the description compensates by naming the key returned fields (id, title, parent, enabled flags), which is what an agent needs to chain into ticket creation. It leaves pagination expectations unaddressed, but that is partly covered by the schema's page/count definitions.

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

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

Schema description coverage is 100%: both page (starting at 1) and count (1-200) are fully documented in the schema with ranges. The description adds no extra meaning about pagination, 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 the ticket departments") and enumerates the returned fields (id, title, parent, tickets/chat enabled flags), making the scope unambiguous against siblings like deskpro_list_ticket_statuses or deskpro_list_agents. The Deskpro endpoint reference pinpoints exactly which collection is targeted.

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?

"Needed to route a new ticket" supplies a concrete when-to-use context, implicitly tying this call to deskpro_create_ticket. However, it names no alternative tools and gives no exclusions or prerequisites, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, covering safety. The description adds the endpoint (GET /api/v2/organizations), which confirms read-only nature and source, but does not disclose pagination behavior, response format, or rate limits. With annotations present, this is an appropriate baseline.

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 with zero waste, and the primary purpose is front-loaded before the technical endpoint detail. It is appropriately sized for a simple list operation.

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

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

Given the tool's simplicity, full schema coverage, and annotations covering read-only safety, the description is nearly complete. It could briefly mention that results are paginated (since page and count exist), but the schema covers those parameters and no output schema requires return value explanation.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description echoes filtering by name or labels but adds no syntax or format beyond what the schema provides, making the baseline score of 3 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?

The description states a clear verb 'List' and resource 'customer organizations', and mentions filtering. However, it does not explicitly differentiate itself from sibling tools such as get_organization or create_organization, leaving the agent to infer scope.

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 when-to-use or when-not-to-use guidance is provided beyond the implicit act of listing. The description does not mention alternatives like get_organization for single lookups or create_organization for creation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/v2/organizations/{id}/tickets), which is mild corroborating context but discloses nothing about pagination limits, ordering, or result volume.

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-loaded with the purpose and followed by the API mapping. Nothing is wasted, though the endpoint restatement is only marginally useful to an agent.

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, three-parameter list tool with full schema coverage and annotations covering safety, the description is sufficient. No output schema exists, so return values need not be explained, but pagination behavior is left entirely 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%, so organization_id, page, and count are all documented in the schema with types and bounds. The description adds no parameter-level meaning beyond what the schema already provides, 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 and resource with a clear scope qualifier ('belonging to one organization'), which implicitly separates it from deskpro_list_tickets and deskpro_list_person_tickets. It never names those siblings, so an agent must infer the distinction rather than being routed.

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 scoping phrase 'one organization' implies when this tool is the right choice, but there is no explicit when-to-use, when-not-to-use, or alternative naming. Usage is left to inference from the sibling list.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the underlying endpoint (GET /api/v2/people) and no pagination, result shaping, or side-loading behavior of its own, so it adds little beyond the structured data.

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 resource and its filtering dimensions; nothing is wasted and nothing is 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?

For a 9-parameter, fully documented list tool with readOnly annotations, the description covers purpose and filtering adequately. With no output schema, a brief note on the paginated list result and the relationship to deskpro_list_agents would close the 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 description coverage is 100%, so the schema already documents all nine parameters with ranges, enums, and patterns. The description restates the name-search and email/org/agent filters but adds no format, syntax, or defaulting detail beyond the schema, making the baseline 3 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 and resource ("List people") and clarifies scope with the parenthetical "(end users and agents)," plus the filterable dimensions. It is clearly the collection-listing counterpart to the single-record deskpro_get_person, though it never names that sibling to sharpen the distinction.

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

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

Usage is implied by "searchable by name and filterable by email, organization or agent flag," which tells the agent when the filters apply but not when to prefer this over alternatives. It notably fails to route between this tool and the sibling deskpro_list_agents, which overlaps with the is_agent filter.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying REST endpoint, which helps a Deskpro-aware caller, but says nothing about ordering, result shape, or how the person_id must relate to an existing person. Given the annotations carry the safety profile, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the core purpose and with no filler. The endpoint reference is mildly redundant for an agent but cheap and useful for 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 simple read-only list endpoint with fully documented parameters and a safety annotation, the description covers what the agent needs to select and call it. It does not restate return values, which is acceptable with no output schema, though pagination behavior is left entirely 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%, so page, count, and person_id are all documented in the schema; the baseline is 3. The description only restates the person scoping ('one person') and adds no format or constraint 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?

The description states a specific verb (List) and resource (tickets) plus the scoping axis (raised by one person, i.e. a support history), which naturally separates it from deskpro_list_tickets and deskpro_list_organization_tickets. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than stated.

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

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

"their support history" hints at the use case — pulling one contact's ticket log — but there is no explicit when/when-not guidance and no named alternative (e.g. use deskpro_list_tickets for a global feed). 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, so the safety profile is covered. The description goes beyond that by disclosing the shape of the returned payload — replies and agent notes distinguished by an is_agent_note flag, each with author, date, and HTML body — which is real behavioral context. It omits pagination/ordering 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: the payload description comes first, then the endpoint reference. Every clause carries information about scope or returned content; nothing is padded.

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

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

With no output schema, the description usefully compensates by naming the returned fields, and the fully-described input schema carries all parameter detail. The main remaining gap is pagination/ordering guidance for a list endpoint, but overall it is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so page, count, include, and ticket_id are all documented in the schema itself. The description only implies ticket scoping and adds no syntax or format detail beyond the schema, which matches the baseline 3 for a fully-covered 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 (List) and resource (messages on one ticket) with explicit scope ('one ticket'), and enumerates what comes back (replies, agent notes, author, date, is_agent_note, HTML body). This clearly separates it from deskpro_get_ticket and deskpro_add_ticket_message without needing to open a 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 word 'one ticket' and the required ticket_id imply you use this to read a single ticket's conversation, but there is no explicit statement of when to prefer it over deskpro_get_ticket or how it relates to deskpro_add_ticket_message. 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?

The readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds useful context by naming the returned ticket fields and the pagination meta, and notes it maps to GET /api/v2/tickets. It does not mention auth requirements, rate limits, or default page size, so it is additive but not rich.

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

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

Two tightly written sentences that front-load the purpose and filters before the return shape. The trailing API-endpoint reference is marginally redundant metadata but is compact and does not bury the operative content.

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

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

For a read-only list tool with no output schema, the description usefully sketches the return payload (ticket fields plus pagination meta), which compensates for the missing output schema. It is nearly complete; the only real gap is guidance on selecting this tool over its scoped siblings.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, and the description only restates the filter dimensions at a coarser level. It adds no syntax or format detail (e.g., status values or label semantics) beyond what the enum and per-field descriptions provide, 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 tickets") and enumerates the filterable dimensions (status, agent, requester, organization, department, labels) plus sorting. It is clear about what the tool returns, but it never distinguishes itself from similarly named siblings such as deskpro_list_organization_tickets, deskpro_list_person_tickets, or deskpro_search.

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, when-not-to-use, or alternative routing. The agent is left to infer that this is the general ticket-listing endpoint versus the scoped variants (list_person_tickets, list_organization_tickets) or deskpro_search, which is exactly the ambiguity a definition should resolve.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the returned field composition (status_type, status_code, title), which matters because there is no output schema. It omits pagination behavior despite the page/count params.

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

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

Two short sentences with the core purpose front-loaded and no filler. The trailing 'Deskpro: GET /api/v2/ticket_statuses' is slightly redundant for an agent but does map the tool to its API endpoint.

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, naming the returned fields is a meaningful completeness contribution, and all three optional params are documented in the schema. Minor gaps remain around pagination/result-set behavior, but nothing essential to correct invocation 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 page, count, and status_type are already documented with ranges and an enum. The description adds no filtering or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (ticket statuses and custom sub-statuses) and even enumerates the fields returned (status_type, status_code, title). The resource is distinct from sibling tools like deskpro_list_tickets, so an agent can select it without ambiguity.

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 is given, and no alternatives are named. Usage is only implied: an agent can infer this is a lookup for valid status definitions, but the description never states that purpose or contrasts it with deskpro_list_tickets.

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

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

The readOnlyHint annotation already establishes this as a safe read, and the description is consistent with that; it also adds the genuinely useful behavioral detail that results are grouped by type. However, it says nothing about pagination, result caps, or rate limiting, which matter for a cross-entity search.

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 that front-loads the covered entity types, followed by the API mapping. Every clause carries information; the 'GET /api/v2/search' fragment is marginally redundant but harmless.

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 only two parameters, no output schema, and a read-only annotation, the description is adequate but leaves gaps: it never mentions pagination, result limits, or how grouped results should be interpreted, which an agent needs before issuing a broad search.

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 q and types are fully documented in the schema, including the comma-separated format and enum values. The description adds no parameter-level meaning beyond that, 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 concrete verb-and-resource ('Quick search across tickets, people, organizations, articles...') and enumerates the covered entity types, so the agent knows the scope precisely. It does not explicitly contrast itself with the many list_* siblings (e.g. deskpro_list_tickets), leaving the search-vs-list distinction to 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 word 'Quick search' implies a broad, exploratory lookup rather than a targeted fetch, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative (e.g. 'use deskpro_get_ticket for a single known ID'). 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?

Beyond the lone destructiveHint annotation, the description discloses that this is a partial update (unpassed fields are left alone), that changes are reversible by updating again, that the hidden deleted/spam status is not settable, and the underlying PUT endpoint. It does not cover permission/auth requirements or what the response contains, but it adds real behavioral 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?

Three compact sentences with the field list and partial-update rule front-loaded; nothing is padding. The trailing 'Deskpro: PUT /api/v2/tickets/{id}' is mildly redundant for an agent but cheap.

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

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

For a 10-parameter mutation tool with full schema coverage and no output schema, the description supplies the key non-schema facts: partial-update behavior, reversibility, and the unsettable hidden status. Missing only auth/permission notes and error behavior.

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

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

Schema description coverage is 100%, so all ten parameters (including patterns, ranges and the status sub-status format) are already fully documented. The description only restates the field list and the hidden-status restriction, adding no syntax or format meaning beyond the schema — 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 ('Change') plus resource ('a ticket's') and enumerates the full set of mutable fields (subject, status, assignment, department, organization, urgency, hold, labels). This clearly separates it from deskpro_create_ticket, deskpro_get_ticket and deskpro_add_ticket_message without needing 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?

It states partial-update semantics ('Only the fields you pass are sent') and one exclusion ('Cannot set the hidden (deleted/spam) status'), which are useful invocation rules. However there is no explicit when-to-use guidance relative to sibling write tools or prerequisites (e.g. resolving vs adding a reply).

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