deskpro

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

Annotations only supply destructiveHint=true; the description adds the crucial undisclosed behaviors — that is_note=false triggers an email to the requester and 'cannot be unsent', and it names the underlying endpoint. This is real content beyond structured fields.

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

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

Two tight sentences with no filler; the note-vs-reply distinction and its consequence are front-loaded, and the endpoint is appended as low-priority detail.

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

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

For a 4-parameter mutation tool with full schema coverage, no output schema, and only a destructiveHint annotation, the description covers everything an agent needs: the mutation target, the branching mode, and the irreversible side effect.

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 every parameter already carries a description, so the baseline is 3. The description restates is_note semantics (already in the schema) and says nothing about format or ticket_id 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?

States a specific verb (add) and resource (message on a ticket) with an explicit actor ('as the key's agent'), and splits the two modes by is_note. It is clearly distinguishable from the sibling deskpro_list_ticket_messages, which only reads messages.

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

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

Gives clear conditional guidance for the core decision: is_note=true for internal notes, is_note=false for a public reply, plus the consequence that a reply is emailed and irreversible. It does not, however, contrast this tool against siblings like deskpro_update_ticket, so no alternative-routing guidance is offered.

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 carry only destructiveHint=true and a title, so the description does most of the work. It usefully discloses a behavioral trait beyond annotations — email domains auto-associate people with matching addresses — plus the underlying API endpoint, but it omits what happens on duplicate names, permission requirements, or what is returned. Some value added, but the behavioral picture stays thin.

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

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

Three short sentences with no waste: purpose first, the key behavioral nuance second, the API mapping last. Nothing needs trimming.

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 4-parameter create with full schema coverage and no output schema, the description covers purpose and the notable side effect. It is nearly complete, missing only failure/duplicate handling and auth requirements, which are secondary for this tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining the side effect of email_domains (auto-association of matching people), which the schema only describes as domain values. The other three parameters (name, labels, summary) get no extra detail.

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

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

States a specific verb+resource ('Create a customer organization') that is unambiguous against siblings like deskpro_get_organization and deskpro_list_organizations. It does not explicitly name a sibling alternative, but the create verb alone separates it from the read tools.

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

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

No guidance on when to use this versus deskpro_get_organization / deskpro_list_organizations (e.g. check for an existing org first), and no prerequisites such as required permissions or duplicate-name behavior. The agent must infer the usage context entirely.

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

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

Adds real side-effect context beyond the destructiveHint annotation: Deskpro auto-creates a person when the email is new, and triggers may send an email to the requester. It also states the tool returns the created ticket. It does not contradict destructiveHint=true, which aligns with a write operation that can create subsidiary records.

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 tightly packed sentences with zero filler; the requester identification rule is front-loaded and the endpoint reference closes it out.

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 two required inputs, requester resolution, ticketing side effects, and the return value. It leaves per-parameter detail to the thorough schema, which is appropriate.

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 the person_id-vs-person_email resolution rule and the auto-creation behavior of a new email, which the schema only implies via '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') plus the requester resolution model (person id or email) and the requirement of a first message. An agent can distinguish it from deskpro_add_ticket_message (which adds to an existing ticket) 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?

Explains the two ways to identify the requester and clarifies that an unknown email triggers person creation. It stops short of explicitly naming alternatives (e.g. use deskpro_add_ticket_message for existing tickets), but the context is clear enough to select the tool correctly.

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 safe-read profile is covered. The description adds valuable behavioral context beyond that by enumerating what the response contains (title, content, status, categories, labels), which is especially useful because no output schema exists. It stops short of covering error handling or permissions.

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

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

The description is two compact clauses: the core action and returned fields, followed by the underlying API endpoint. It is front-loaded with the purpose and contains no filler.

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

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

For a simple single-entity read tool with one fully documented parameter and no output schema, the description provides the essential information: what is fetched, by what identifier, and what fields come back. It is nearly complete, though it could mention not-found behavior or whether any expansion is possible.

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 article_id parameter is fully documented in the schema as a numeric id. The description adds only the phrase 'by id', which mirrors the schema without adding syntax, format, or constraints. Baseline 3 is appropriate when the schema already carries the parameter semantics.

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

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

States a specific verb ('Fetch') and resource ('single knowledgebase article'), scoped by id, and lists the returned fields. The word 'single' implicitly distinguishes it from the sibling deskpro_list_articles, so an agent can identify its purpose without opening the schema.

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

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

The description makes clear it is a get-by-id operation, which is the core usage context. However, it gives no explicit guidance about when to choose this over deskpro_list_articles or deskpro_search, nor any prerequisites or exclusions, leaving usage implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the return contents (auth method, person id, profile) and framing the call as low-cost, which is useful behavioral context for a no-argument identity probe.

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 core purpose before the use case and endpoint mapping. Efficient overall, though the trailing 'Deskpro: GET /api/v2/me' is documentation flavor rather than agent-facing guidance.

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

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

With no output schema, the description carries the burden of describing return values, and it does so explicitly (auth method, bound person id, profile). For a parameter-free identity probe, an agent has everything needed to decide and invoke 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description correctly implies no input is required ('who the API key acts as' is derived from the credential).

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 precise verb+resource (return the identity the API key acts as) and enumerates what comes back: auth method, bound person id, and profile. This clearly separates it from sibling read tools like deskpro_get_person and deskpro_list_agents, which target arbitrary people rather than the caller.

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 use case — 'a cheap way to confirm the helpdesk URL and key are right' — which tells the agent when this call is worthwhile. It stops short of naming an alternative or stating an explicit when-not condition, so it is strong context without 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?

readOnlyHint=true already declares this as a safe read. The description usefully adds what is returned (name, summary, email domains, labels, custom fields, ticket count) and the underlying endpoint, but says nothing about behavior on a missing id (error vs empty) or how the `include` side-loading affects the response.

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, front-loaded with the action and resource, followed by a short endpoint reference. No filler.

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

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

With no output schema, the field enumeration compensates well for what the agent will receive, and the single required id is clear. Only minor gaps remain (error behavior, side-load semantics).

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

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

Schema description coverage is 100%, so both parameters are already documented, including the `include` side-load syntax. The description only echoes the id lookup, adding no meaning beyond the schema.

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

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

States a specific verb and resource ('Fetch a single organization by id') and even enumerates the payload fields, so its purpose is unambiguous. It distinguishes itself from deskpro_list_organizations only implicitly via 'single'; no sibling is named explicitly, so it falls short of a 5.

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

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

Usage is implied – fetch one record when you have its numeric id – but there is no explicit when-to-use guidance, no mention of prerequisites or permissions, and no routing to list/search alternatives for discovery.

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 usefully adds the upstream endpoint (GET /api/v2/people/{id}) and the shape of returned data, but says nothing about failure behavior (e.g. unknown id), permissions, or the `linked` section.

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 purpose and returned payload come first, the endpoint mapping trails. No filler, nothing redundant.

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

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

With no output schema, the description carrying the returned-field inventory is genuinely valuable and mostly sufficient for an agent to call it. It stops short of covering error/not-found behavior or permissions, but for a simple read-by-id tool that gap is minor.

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

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

Schema description coverage is 100%, and both person_id and the include side-loading parameter are described in the schema itself (including the `linked` section). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Fetch a single person by id') and even enumerates the fields returned. The singular, id-scoped framing implicitly separates it from deskpro_list_people, but no sibling is named explicitly, which keeps it short of a 5.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative (e.g. deskpro_list_people or deskpro_search) guidance. The 'by id' phrasing faintly implies a known numeric id is required, but that is inference rather than stated 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, so the safety profile is covered. The description adds real behavioral context beyond that: the merged-ticket redirect semantics and the exact fields returned, which an agent cannot get from annotations or schema.

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

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

Two sentences, no filler; the core purpose and returned field list are front-loaded, with the merged-ticket caveat and endpoint reference trailing compactly.

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 returned fields and covers the merged-ticket redirect quirk, which is the main non-obvious behavior. It stops short of noting error behavior for a missing/invalid ticket, but is largely complete for a simple read tool.

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

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

Schema description coverage is 100%, so both parameters (ticket_id and include) are already documented in the schema. The description adds no syntax or format detail beyond the schema and never mentions the include side-loading parameter, so baseline 3 is appropriate.

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

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

States a specific verb (fetch) and resource (a single ticket by id) and enumerates the payload's contents. It implicitly distinguishes itself from deskpro_list_tickets and deskpro_search by scoping to one ticket identified 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?

Usage is implied by 'by id' – an agent knows it needs a numeric ticket id – but there is no explicit when-to-use/when-not guidance and no mention of alternatives like list_tickets or search when the id is unknown. Adequate but leaves routing 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=true already tells the agent this is a safe read, so the description's added value is the shape of the result (id, name, email, online state) and the underlying endpoint GET /api/v2/agents. That field disclosure is genuinely useful given there is no output schema, though pagination/filter behavior is left to the schema.

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

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

A single front-loaded sentence delivers purpose, payload, and use case, with the API endpoint appended compactly. No filler or redundancy.

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

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

For a zero-required-parameter read-only list tool, the definition covers purpose, use case, and returned fields, and the schema covers all inputs. Without an output schema the field list compensates well, though pagination behavior on the response side is only implied by the input parameters.

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%, with page, count, and online all fully documented including the -1/0/1 semantics of online. The description adds nothing beyond that, so the baseline 3 is correct — the schema carries parameter meaning entirely.

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

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

States a specific verb and resource ('List the helpdesk's agents') and immediately names the returned fields (id, name, email, online state), which separates it from siblings like deskpro_list_people and deskpro_list_organizations. The stated purpose (assigning a ticket) sharpens the distinction further.

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 clear context for use — 'needed to assign a ticket' — which tells the agent when this tool is relevant. It does not, however, name an alternative or a when-not condition (e.g., use list_people for end-users), 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, so the safe-read profile is covered by structured data. The description adds only the underlying endpoint (GET /api/v2/articles), which is minor context; it says nothing about pagination behavior beyond what the schema already exposes, so it earns a baseline 3.

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 plus an endpoint reference, with the core purpose front-loaded. Nothing is wasted, though the endpoint clause adds little for an agent that already knows the tool name.

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

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

For a read-only list tool with no output schema and full schema coverage, the description is minimally adequate. It does not mention pagination defaults or the shape of returned articles, which an agent calling a paged list endpoint would benefit from, but annotations cover the safety profile.

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 six parameters (including page, count, order_by and their bounds) are documented in the schema. The description names a subset of filters (category, status, author) but adds no format or semantics beyond the schema, which is the expected baseline when the schema does the work.

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 knowledgebase articles') and names the filter dimensions, which cleanly separates it from the singular deskpro_get_article sibling. It stops short of explicitly contrasting with other list tools (e.g. deskpro_search), so it is clear but not fully sibling-differentiated.

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

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

There is no guidance on when to use this tool versus deskpro_get_article or deskpro_search, and no prerequisites or exclusions. The only usage signal is the bare phrase 'filterable by category, status and author', which implies filters exist but does not route the agent.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses the shape of results (id, title, parent, enabled flags), but says nothing about pagination behavior despite page/count parameters existing. With annotations carrying the safety burden, 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?

A single dense sentence front-loads the resource and returned fields, followed by the API endpoint. No filler; every clause adds 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?

With no output schema, the description compensates by listing the salient returned fields, and the workflow purpose (routing a ticket) is stated. It is nearly complete; only pagination semantics are 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 the schema fully documents page and count. The description adds no parameter syntax or defaults beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (ticket departments) and even previews the returned fields (id, title, parent, tickets/chat enabled). The added 'needed to route a new ticket' framing makes its role distinct from unrelated list_* siblings like deskpro_list_agents or deskpro_list_articles.

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 — the departments are 'needed to route a new ticket', implying it should be called before deskpro_create_ticket. No explicit exclusions or named alternatives are given, but the workflow cue is strong.

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

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

readOnlyHint=true already declares the safe read profile, so the description merely needs to add context. It adds the upstream endpoint (GET /api/v2/organizations), which corroborates the read semantics, but says nothing about pagination defaults (page/count), result limits, or the `linked` side-loading behavior implied by the include 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?

Two short, front-loaded sentences with zero filler: the capability first, the endpoint reference second. Nothing is repeated or wasted.

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 six-parameter list tool with no output schema, the description does not mention pagination behavior or the shape/side-loading of results, leaving the agent to infer from the schema. Adequate but with clear gaps for a listing endpoint.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description only echoes the name and labels filters and adds no syntax or behavioral detail (e.g., how `search` differs from `name`, or pagination defaults), so baseline 3 applies.

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

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

States a specific verb+resource ("List customer organizations") and adds the filterable dimensions (name, labels), so it is clearly distinguishable from deskpro_get_organization and deskpro_create_organization. It stops short of explicitly naming sibling tools or scoping against deskpro_list_people/list_agents, so it is clear but not differentiated from siblings.

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

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

There is no when/when-not guidance and no mention of alternatives such as deskpro_search or deskpro_get_organization for single-record lookup. The filterable-by-name-or-labels clause hints at usage but does not tell the agent which tool to pick under which condition.

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 safe-read profile is covered. The description adds only the underlying API endpoint, which does not tell the agent anything about pagination behavior, ordering, or result size limits that the page/count params imply. Useful but thin 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?

Two short sentences, zero waste, with the purpose front-loaded and the endpoint reference relegated to second position. 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?

For a read-only list tool with fully documented parameters, no output schema, and an annotation covering safety, the description is nearly complete. The only gap is that return shape and pagination expectations are left entirely to inference, which is minor given the simple contract.

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 page, count, and organization_id all documented in the schema itself, so the baseline is 3. The description adds no format, default, or constraint details beyond what the schema already provides.

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

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

States a specific verb (List) and resource (tickets) with a clear scope qualifier (belonging to one organization), which distinguishes it from deskpro_list_tickets and deskpro_list_person_tickets by inference. It does not name those siblings explicitly, so it stops short of a 5.

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

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

Usage is only implied by the scope phrase 'belonging to one organization'; there is no explicit when-to-use, when-not-to-use, or named alternative for listing tickets across all organizations or for a person. The required organization_id param signals the context but the description adds no 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, so the safe-read profile is covered. The description adds the underlying endpoint and enumerates filterable dimensions, but says nothing about pagination behavior or result volume beyond what the schema implies.

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

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

Two tight sentences, zero waste, with the resource and its scope front-loaded and the endpoint appended. Nothing extraneous.

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 and a readOnly annotation, most agent needs are met and no output schema is expected to be explained. The only meaningful gap is the unaddressed relationship to deskpro_list_agents, which is a real disambiguation need.

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 9 parameters thoroughly. The description restates the filterable dimensions (name, email, organization, agent flag) without adding syntax, format, or interaction detail, so baseline 3 applies.

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

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

Specific verb+resource ("List people") with useful scope clarification that it covers both end users and agents. However, it does not distinguish itself from the sibling deskpro_list_agents, an obvious overlap, nor from deskpro_get_person for single-record lookups.

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 guidance or alternatives named. Given a sibling literally called deskpro_list_agents, an agent needs to know whether to call this tool or that one, and the description never addresses it. The filter hints describe capability, not usage context.

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-destructive read, so the description need not restate that. It adds the underlying REST endpoint (GET /api/v2/people/{id}/tickets), which is modestly useful context, but says nothing about pagination behavior, result volume, or what 'no tickets' looks like.

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 stating the action and scope, followed by the endpoint reference. No filler, no redundancy with the title or schema.

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 read tool with full schema coverage and a readOnlyHint, the description covers the essentials. The main omission is return shape — with no output schema, the agent gets no hint whether the response is a bare array or a paginated envelope with totals.

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 page, count, and person_id all documented in the schema itself (including the 1-200 range on count). The description adds only the implicit notion that person_id identifies the person whose tickets are returned, matching the baseline 3 when the schema carries the load.

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

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

Specific verb ('List') and resource ('tickets') with an explicit scope qualifier: 'raised by one person'. That scope naturally separates it from deskpro_list_tickets and deskpro_list_organization_tickets, though those siblings are never named outright.

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' implies the use case of reviewing one person's past tickets, but there is no explicit when-to-use statement and no exclusion or alternative routing (e.g., use deskpro_list_tickets for a broad feed). Usage must be inferred from the phrasing.

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 profile, and the description adds useful content by naming what comes back (author, date, is_agent_note flag, HTML body). It does not discuss pagination behavior or that notes vs replies are interleaved, so it does not go much beyond the annotation plus 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 compact sentences with the core purpose front-loaded, followed by a terse API reference. No filler or redundancy.

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

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

With no output schema, the description compensates by enumerating the returned fields, and the schema fully covers parameters. Minor gaps remain around pagination/response envelope, but an agent can call this correctly from what's given.

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 page, count, include and ticket_id are all documented in the schema; the description only reasserts that the scope is a single ticket. No additional format or semantics are added, 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 (a ticket's conversation: replies and agent notes) scoped to 'one ticket', and even names the exact returned fields. This clearly distinguishes it from deskpro_list_tickets (all tickets) and deskpro_add_ticket_message (write).

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 'on one ticket' scoping implies when to use it versus the list-all-tickets sibling, but no explicit when/when-not guidance or named alternatives are given. Usage is inferable 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 establishes this as a safe read. The description adds genuinely useful context beyond annotations (the ticket object fields returned and the presence of pagination meta) plus the underlying endpoint, but says nothing about auth requirements or rate limits.

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

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

Two compact sentences, front-loaded with the verb and resource, then filters, then return shape and endpoint. Slightly list-heavy but every clause carries 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?

With 12 optional parameters and no output schema, the description usefully states the return fields and pagination meta, covering the main gap. It is somewhat incomplete on pagination controls (page/count) and the side-loading include parameter, but is otherwise adequate 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 baseline is 3. The description names a subset of filters (status, agent, requester, organization, department, labels) and sorting but omits ids, page, count, include and group_sort, adding no semantics 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 tickets') and enumerates the filter/sort dimensions, so the agent knows exactly what the tool retrieves. It does not differentiate itself from overlapping siblings such as deskpro_list_organization_tickets or deskpro_list_person_tickets, which are scoped subsets of the same resource.

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

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

The filter list implies when this generic list is useful, but there is no explicit when-to-use or when-not-to-use guidance, and no routing to the several sibling list tools that cover narrower scopes (organization tickets, person 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the resource scope (helpdesk-configured statuses and custom sub-statuses) and the API endpoint, which is modest value, but it says nothing about pagination limits or result ordering behavior.

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

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

Two tightly packed sentences with the main purpose front-loaded and the endpoint trailered. The parenthetical is slightly ambiguous as to whether it describes returned fields or the status_type parameter, but nothing is wasted.

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 parameterless read-only list tool with full schema coverage and no output schema, the description covers the resource, the returned field shape, and the underlying endpoint. Only pagination/return-envelope behavior is unaddressed, 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%, so page, count, and the status_type enum are fully documented in the schema already; baseline 3 applies. The parenthetical field list hints at status_type but reads more as return fields than as input semantics, adding little 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 (List) and resource (ticket statuses and custom sub-statuses) configured on the helpdesk, and names the fields returned (status_type, status_code, title). No sibling tool overlaps with this resource, so the agent can distinguish it immediately.

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 offers no when-to-use context, no prerequisites, and no alternatives; usage is only implied by the tool name. It does not say whether this is needed to resolve status codes before calling deskpro_list_tickets or deskpro_update_ticket.

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

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

The readOnlyHint annotation already declares this is a safe read, so the description's contribution is modest. It does add one useful behavioral detail beyond the annotations - results are grouped by type - but says nothing about result limits, pagination, or ordering.

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

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

A single compact sentence with the core capability and result shape front-loaded, followed by a brief API reference. No filler, though listing all eight entity types is slightly verbose.

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 two-parameter search with full schema coverage and no output schema, the description covers the scope and the grouped-result behavior adequately. Return-value details beyond grouping are unnecessary given the simplicity of the tool.

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

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

Schema description coverage is 100%, so both q and types are fully documented in the schema, including the comma-separated type format and the omit-for-all default. The description adds no parameter semantics beyond that, 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 (search) and enumerates the resources it spans (tickets, people, organizations, articles, etc.), so an agent knows this is a cross-entity keyword search. It is reasonably distinguishable from the get_*/list_* siblings, though it never explicitly contrasts itself with deskpro_list_tickets or deskpro_list_people.

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: 'quick search' suggests keyword lookup rather than enumeration, but there is no explicit guidance on when to use this versus the numerous list_* tools, and no exclusions or prerequisites are given.

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

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

Annotations only declare destructiveHint=true, so the description carries most of the burden and does add real value: partial-update semantics (unsent fields are untouched), reversibility via a follow-up update, and the constraint that the hidden deleted/spam status cannot be set. It stops short of permissions, audit effects, or status-transition rules, so 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?

Four tight sentences, no filler. The scope read comes first, followed by merge semantics, reversibility, and the one hard constraint, with the HTTP endpoint trailing as reference.

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

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

For a 10-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers merge behavior, reversibility, and the main constraint. Gaps remain around permissions and whether status changes trigger notifications, but nothing needed to invoke the tool 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 the baseline is 3. The description adds meaning beyond the schema in two places: it clarifies that omitted parameters are left unchanged (critical for a PUT-style endpoint) and that the hidden status is not settable, which reinforces the status pattern constraint.

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 ("Change a ticket's ...") and enumerates the exactly-updatable surface: subject, status, assignment, department, organization, urgency, hold state, labels. An agent can immediately distinguish this from deskpro_create_ticket or deskpro_add_ticket_message 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?

"Only the fields you pass are sent" and "Reversible by updating again" give useful operational context, and the hidden-status exclusion is a soft when-not. However, no alternative is ever named (e.g., reply via deskpro_add_ticket_message, read via deskpro_get_ticket), so the agent must infer when this tool beats its siblings.

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