trengo

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

Annotations only supply destructiveHint=true; the description adds genuinely useful behavioral context by stating the operation is reversible via reassignment and that it targets either a user or a team. It stops short of covering auth requirements, whether the assignee is notified, or what the response contains, so it is strong but not exhaustive.

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 that are front-loaded with the core action, then reversibility, then the API endpoint. No filler, and nothing important 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 five-parameter mutation with no output schema, the description covers purpose, target selection, the optional note, and reversibility. It omits prerequisites for sourcing the user/team IDs and any note on side effects such as notifications, which keeps it just under fully complete.

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

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

Schema description coverage is 100% and the schema already documents the type enum and the conditional requirement that team_id is needed for type=team and user_id for type=user. The description restates the user/team choice and the optional note, adding no format or syntax 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 (assign) plus the resource (ticket) and the two target kinds (user or team), plus an optional note. An agent can distinguish this from siblings like trengo_close_ticket, trengo_reopen_ticket, or trengo_send_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?

Usage is implied — assigning when a ticket needs an owner — but there is no explicit when-to-use guidance, no mention that user_id/team_id must first be obtained from trengo_list_users or trengo_list_teams, and no exclusion of related siblings.

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

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

Annotations only convey destructiveHint=true; the description adds the crucial reverse operation (reopen) and the underlying endpoint POST /tickets/{ticket_id}/close, which tells the agent the effect is a state mutation that can be undone. That is genuine added context 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?

One compact sentence covering action, optional parameter, reverse operation, and endpoint — every clause earns its place with no repetition of the name or title.

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

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

For a two-parameter destructive mutation with no output schema, the description supplies reversibility, the optional parameter's source, and the HTTP endpoint. The only minor gap is the absence of any return/confirmation detail, but that is largely covered by the annotation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by framing ticket_result_id as an optional ticket result and pointing to the tool that enumerates valid results, giving the agent a way to resolve the value rather than guessing.

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 ('Close a ticket') and immediately qualifies the optional ticket result, which cleanly distinguishes it from create/update/reopen 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?

Explains the optional result path by pointing to trengo_list_ticket_results and names trengo_reopen_ticket as the inverse operation, so the agent knows the surrounding workflow. It stops short of stating explicit when-not conditions, but the routing context is clear.

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

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

Annotations already flag destructiveHint=true, and the description does not contradict that. It adds useful context (the underlying POST endpoint, where to find the board id), but says nothing about required permissions, side effects on the board/stage, or rate limits beyond what annotations cover.

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 purpose followed by the id-location hint and the endpoint. No filler; every sentence contributes something.

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 create tool with no output schema and full schema coverage, the description covers purpose, id sourcing, and the API path. It lacks any note on permissions or what happens to the created card, but that is a minor gap given the annotations and schema carry the rest.

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 real value by explaining where the required board_id comes from (the board's URL in Trengo), which the schema does not say. It does not otherwise describe stage_id or name 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?

The description names a specific verb and resource ('Create a card ... in a stage of a Trengo board') and gives examples of what a card represents (deal or task). It is clearly distinct from the sibling trengo_update_board_card, though it does not explicitly name that sibling.

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 statement of when to use this versus edit or move a card via trengo_update_board_card, no prerequisites, and no exclusions. The only guidance is locational ('the board id is in the board's URL'), which helps discovery but is not usage guidance.

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

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

Annotations only supply a title and destructiveHint=true, so the description bears most of the behavioral burden. It usefully adds the channel-scoping rule and identifier format per channel, but says nothing about duplicate handling, required permissions, or failure behavior for an operation flagged destructive.

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, front-loaded with the action and scope, followed by the identifier rule and endpoint. 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 required-2-of-3-parameter create tool with full schema coverage and no output schema, the description supplies what an agent needs to invoke it correctly. The only gap is edge-case behavior (duplicates, permissions), which is minor at this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema's generic 'Email address or phone number, depending on the channel' by enumerating which channels map to which identifier form (email vs WhatsApp/SMS/voice).

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 (create) and resource (contact) scoped to a channel, and the API mapping 'POST /channels/{channel_id}/contacts' removes ambiguity. It is clearly distinguishable from sibling create/read tools like trengo_create_ticket and trengo_get_contact.

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 usage by noting the contact must belong to a channel and that the identifier depends on channel type, which is the key precondition. However, it never states when to use this versus trengo_update_contact, nor what happens if the contact already exists — no explicit alternatives or exclusions.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the load, and it delivers the key non-obvious behavior: no customer-facing message is sent as a side effect of creation. It stops short of covering failure modes, duplicate-ticket behavior, or required permissions. The creation framing is not a genuine contradiction of destructiveHint, which here plausibly signals state mutation rather than data loss.

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 action and immediately followed by the single most decision-relevant side-effect fact. No filler or restated title 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 three-parameter creation tool with no output schema, the description covers the action, the prerequisite (existing contact), the channel scoping, and the absence of automatic customer notification. What is missing is only ancillary: error behavior and whether duplicate tickets are permitted.

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 channel_id and contact_id are already documented, and the description adds only the requirement that the contact already exist. It adds no syntax, format, or optionality guidance beyond the schema's 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 ('Open a new ticket') plus a binding constraint ('for an existing contact on a channel'), which separates it from sibling creation tools like trengo_create_contact and trengo_create_board_card. The API endpoint reference reinforces what the call does.

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 a clear workflow cue: creating a ticket alone does not notify the customer, and trengo_send_ticket_message is required to do so. That effectively tells the agent when this tool is a preliminary step, though it never states when to prefer a different ticket tool or what happens if the contact or channel is invalid.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, lowering the burden. The description adds the useful nuance that response/resolution times are reported both with and without business hours, but says nothing about pagination, result volume, or permission requirements. With annotations covering 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?

A single front-loaded sentence that lists the metrics, followed by a short API endpoint mapping. Nothing is padded. The 'Trengo: GET /reporting/agent_performance' clause is mildly redundant but useful for endpoint identification.

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's enumeration of returned metrics does valuable work in telling the agent what comes back. The 7 filter parameters are covered by the schema. The only gap is behavioral detail (pagination, date-range semantics), which is minor for a read-only reporting 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 the schema fully documents all seven parameters, including the paired start_date/end_date constraint. The description adds no parameter-level meaning beyond this, so the baseline of 3 is appropriate.

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

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

The description names the specific resource (per-agent performance) and enumerates the exact metrics returned: messages sent, notes, tickets assigned/closed, first response and resolution times. An agent immediately knows what the tool produces. It does not, however, distinguish itself from reporting siblings such as trengo_get_reporting_metrics or trengo_get_ticket_details_report.

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 guidance on when to use this tool versus the other reporting tools in the sibling list, nor any stated prerequisites. The phrase 'over a period' weakly implies a date-scoped reporting call, but the agent must infer this. No exclusions or alternatives are mentioned.

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 the useful payload detail (name, email, phone, custom field data, optional notes), which substitutes for the missing output schema. It does not mention permission requirements or behavior when the id does not exist, 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 terse sentences, the return payload front-loaded and the API mapping trailing as useful metadata. No filler.

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

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

With no output schema, the description usefully summarizes the returned fields, which is what an agent needs for a simple point lookup. It stops short of covering error/not-found behavior or whether custom fields are always populated.

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 in the schema; the description's 'optionally with notes' merely restates include_notes. Baseline 3 is correct when the schema carries 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 singular resource (one contact), enumerates the returned fields, and maps to the concrete API call GET /contacts/{id}. The singular scope clearly distinguishes it from the sibling trengo_list_contacts.

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

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

Usage is only implied: the singular 'one contact' plus the required contact_id signal this is a point lookup rather than a listing. There is no explicit statement of when to use this instead of trengo_list_contacts or how it relates to trengo_update_contact.

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 safety bar is lowered. The description adds the returned field set and the 'must be an email message' precondition, but says nothing about behavior when the message is not an email (error vs empty), auth scope, or pagination — none of which is needed here given the single-resource read, but it is not rich either.

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: the capability and its return fields come first, the constraint and endpoint second. No filler or restatement of the title.

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

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

With no output schema, the description carries the return-value burden and does so by naming the fields (HTML body, from, to, subject, Message-ID). The only gap is undefined behavior when the target message is not an email, which is minor given a simple two-id read.

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 only two integer ids, so the schema fully documents the parameters. The description restates the required inputs only via the endpoint path (ticket_id, message_id) and adds no format or sourcing detail beyond that. 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 and resource ('Fetch the full email behind one message of a ticket') and enumerates what comes back: original HTML body, from, to, subject, Message-ID. This plainly distinguishes it from trengo_list_ticket_messages, which lists messages rather than retrieving one email's full payload.

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?

Implicit usage is derivable from 'behind one message of a ticket' and the constraint 'The message must be an email message,' but there is no explicit when-to-use guidance or named alternative (e.g., list_ticket_messages for non-email messages). Adequate at the minimum-viable level.

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 genuine behavioral detail beyond that by disclosing the unit (seconds) for the two time-based metrics, which is absent from the schema enum values. It still says nothing about pagination, result limits, or permission requirements.

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

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

Two dense sentences that front-load the aggregation scope and finish with filter dimensions, followed by a short endpoint mapping. The 'Trengo: GET /reporting/metrics' line is mildly redundant but useful for API traceability.

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 returnable metrics and notes the unit for the time metrics, so an agent knows what comes back. Remaining gaps are pagination behavior and date-pair requirements, which are partly covered by the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description's 'filter by team, channel, label or direction' restates what the schema already says without adding format or semantics 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 specific verb (aggregate) and resource (support metrics) and enumerates exactly which metrics are returned, so the tool's output scope is unambiguous. It does not, however, distinguish itself from close siblings like get_agent_performance or get_ticket_details_report, which also return support analytics.

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

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

The description implies usage by naming the filtering dimensions (team, channel, label, direction) and the aggregation period, but gives no explicit when-to-use guidance and never names an alternative. An agent must infer whether to reach for this rather than get_agent_performance.

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 readOnlyHint=true, and the description adds real context beyond that: the exact metric columns returned (first reply, first/total resolution, with and without business hours), the filterable dimensions, the sort capability, and the keyset-pagination caveat. It does not mention auth requirements, default date-window limits, or how to obtain the next cursor.

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 sentences, front-loaded with what the report returns before filters, sorting, pagination, then the underlying endpoint. Dense but every clause carries information; the trailing 'Trengo: GET /reporting/details/ticket' is the least essential but still anchors the tool to a concrete 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 15-parameter, zero-required reporting tool with no output schema, the description covers the returned row shape, the filter surface, sorting, and the pagination strategy. Missing pieces are the default/required date-range behavior and cursor handling for subsequent pages, which keep it short of fully self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaning beyond the schema by pairing the timing metrics with their 'with and without business hours' variants, clarifying why both regular and _opening_hours sort options exist, and by summarizing the filter families and the start_after_ticket_id/page substitution rule.

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 ('Per-ticket reporting rows') and enumerates the returned fields (status, assignee, labels, first reply, resolution times), which clearly separates it from aggregate siblings like trengo_get_reporting_metrics and trengo_get_agent_performance. It never names those siblings, so differentiation is inferable rather than explicit.

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

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

The one genuine usage rule given is pagination: 'For large accounts page with start_after_ticket_id instead of page,' which is useful and conditional. However, there is no guidance on when to prefer this report over trengo_get_agent_performance, trengo_get_reporting_metrics, or trengo_list_tickets, so alternative selection is left to inference.

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

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

The readOnlyHint=true annotation already establishes the safe-read profile, and the description adds the underlying endpoint (GET /contact_groups) plus the fact that returned ids drive updates. It says nothing about pagination behavior or result volume, which matters for a paged 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?

A single compact sentence with the core action front-loaded, followed by the downstream-use hint and the API endpoint. 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 read-only list tool with an annotation covering safety, a fully documented schema, and no output schema, the description is nearly sufficient. The only missing nicety is guidance on paginating through large group lists.

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

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

Only one optional parameter and schema_description_coverage is 100%, so the schema already documents the 1-based page number. The description adds no syntax or defaulting detail 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 and resource ('List the contact groups in the account'), and ties the result to a downstream action by naming trengo_update_contact, which distinguishes it from the other trengo_list_* siblings that cover labels, teams, users, and custom fields.

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 clause 'use their ids with trengo_update_contact' tells the agent when this tool is worth calling and what it feeds into. There is no explicit when-not guidance or exclusion, but the intended workflow context is clear.

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 read. The description adds only the endpoint mapping (GET /contacts); it doesn't disclose pagination behavior, result ordering, or what happens when term matches nothing, so added value over annotations is modest.

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

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

Two short sentences, purpose front-loaded before the endpoint note; nothing is wasted. It is efficient though not especially information-dense.

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/search tool with fully documented parameters and no output schema, the description covers what an agent needs to call it correctly. The missing piece is what the return payload looks like and how paging results behave, which is minor here.

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

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

Schema description coverage is 100%, so page, term, and include_last_interaction are already documented in the schema. The description restates the match fields for term but adds no syntax, format, or behavior 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 (list/search) and resource (contacts) plus the searchable fields, so the agent knows exactly what the tool does. It doesn't contrast itself with siblings like trengo_get_contact or trengo_list_contact_groups, 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 implied: use with no term to list, with a term to search. There is no explicit guidance on when to prefer this over trengo_get_contact (single contact) or other list_* siblings, and no prerequisites or exclusions are mentioned.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds the API mapping (GET /custom_fields), which is minor context, but says nothing about pagination behavior or the shape of the returned field definitions.

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, resource and scope front-loaded with no filler. The trailing endpoint reference is slightly redundant but costs almost nothing.

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

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

For a simple read-only list tool with one optional param, no output schema and a readOnlyHint annotation, this covers what the agent needs: what is listed and for which entities. No return-value explanation is required.

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

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

Only one optional parameter (page) with 100% schema description coverage, so the schema already documents it fully ('Page number (1-based). Omit for the first page.'). The description adds no parameter detail, which is acceptable per the high-coverage 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 (List) and resource (custom fields) and scopes it to tickets, contacts and profiles, which distinguishes it from list_labels, list_contacts and other list siblings. It stops short of explicitly naming an alternative tool, but the resource is unambiguous.

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

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

The description gives no when-to-use or when-not-to-use guidance and names no alternatives among the many list_* siblings. Usage is only implied by the verb '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 safety is covered. The description adds the underlying endpoint ('Trengo: GET /labels'), which is useful provenance, but says nothing about pagination behavior or result ordering despite exposing a page 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 tight sentences with the resource front-loaded and the endpoint reference appended as a compact identifier. No filler or redundancy.

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

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

For a simple read-only list tool with one optional parameter and a safe annotation profile, the description is nearly sufficient. The only gap is that no output schema exists, so the shape of returned labels and any pagination semantics are left unexplained.

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 'page' parameter is fully documented in the schema, so the description need not add syntax. It adds no meaning 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 (List) and resource (ticket labels/tags) scoped to the account, and clarifies the synonym 'tags' which aids matching. It does not explicitly differentiate from the many sibling list_* tools, but the resource noun makes it unambiguous.

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

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

The phrase 'for filtering tickets and reports' implies downstream usage context, but there is no explicit statement of when to call this versus alternatives such as trengo_list_custom_fields or trengo_list_tickets, nor any prerequisite conditions.

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

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

The readOnlyHint=true annotation already establishes this is a safe, non-mutating read, so the description's burden is lower. It adds only minor context ('saved', optional type filter, endpoint mapping) and says nothing about pagination, ordering, or what an empty result means.

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

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

A single tightly written sentence that front-loads the core action and appends the endpoint reference without padding. Nothing is wasted, though the endpoint mention is marginally redundant with the tool's purpose.

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 with a fully described schema and safety annotations, the description covers what an agent needs to select and call it. Return-value behavior is unexplained, but no output schema exists and a plain list tool rarely requires it.

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 'type' parameter with its MESSAGING/EMAIL enum is fully documented in the schema itself. The description merely restates that filtering is optional ('optionally only the messaging or email ones'), 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 the saved quick replies') and clarifies with a synonym ('canned responses') plus the underlying endpoint (GET /quick_replies). It is unambiguous, though it does not need to differentiate from siblings since no other quick-reply tool exists in the set.

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

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

The phrase 'useful for drafting consistent answers' gives a hint of when the tool is applicable, but there are no explicit when-not conditions and no named alternatives among the sibling tools. Usage is 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?

readOnlyHint=true already declares the safety profile, so the description's main additions are the upstream endpoint (Trengo: GET /teams) and the id-usage note. It says nothing about pagination behavior despite the page parameter, or about the shape/limits of the returned list.

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 with the core capability and purpose front-loaded. The trailing endpoint citation is marginally useful for debugging but is essentially restatement overhead.

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

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

For a simple read-only list tool with no output schema, the description conveys what is returned (teams and their ids) and what to do with it. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% for the single page parameter, which is already documented as 'Page number (1-based). Omit for the first page.' The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('List the teams in the account') and adds the downstream purpose of the returned ids. It does not explicitly differentiate itself from sibling list tools (list_users, list_contact_groups), but the resource is unambiguous.

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

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

'use their ids to assign tickets to a team' gives clear context for when an agent needs this tool — it feeds trengo_assign_ticket. There is no explicit when-not-to-use or named alternative, so it stops short of a 5.

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

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 bar is lower; the description usefully adds what the listing contains (message direction categories plus the contact/agent behind each). However, it says nothing about pagination behavior despite the page parameter, or about ordering, which matters 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?

A single tight sentence followed by a compact endpoint reference. The scoping information is front-loaded and 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 read-only list tool with annotations covering the safety profile, a fully documented schema, and no output schema, the description covers purpose and content adequately. It is slightly short of complete because ordering and pagination behavior on a paginated list are never mentioned.

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

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

Schema description coverage is 100% and both parameters (ticket_id, page) are documented in the schema, so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema already provides, making the baseline 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?

States a specific verb (List) and resource (messages of one ticket) plus the payload scope — inbound, outbound and internal notes — and even names the underlying endpoint. An agent can distinguish it from siblings like trengo_send_ticket_message or trengo_list_tickets 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 phrasing 'messages of one ticket' implies you must already have a ticket_id and want its message history, but there is no explicit when/when-not guidance or named alternative (e.g. trengo_list_ticket_results, trengo_get_email_message). 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?

The readOnlyHint annotation already tells the agent this is a safe, non-mutating call, so the bar is lower. The description adds the underlying API endpoint (GET /ticket_results) and clarifies the semantic meaning of the returned entities, but says nothing about pagination behavior 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 compact sentences with zero filler; the resource definition and clarifying examples are front-loaded before the endpoint citation.

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

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

For a trivial single-parameter read tool with no output schema, the description covers purpose, semantics of the returned items, and a concrete use context. Only minor gaps remain, such as pagination expectations for a list 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 coverage is 100% and the single 'page' parameter is fully documented in the schema, so the description correctly does not duplicate it. Baseline 3 applies since the description adds no parameter-level meaning 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 (List) and resource (ticket results), then clarifies what that resource actually is with concrete examples ('Resolved', 'Sale'). This distinguishes it from siblings like trengo_list_tickets and trengo_list_labels without requiring the schema to be opened.

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 'that can be applied when closing a ticket' implies the tool is a prerequisite lookup for trengo_close_ticket, which is useful contextual routing. However, it never explicitly states when to call it versus alternatives, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds meaningful context beyond that: the token-scoped visibility, the default newest-first ordering, and that each result carries its channel and latest message. It does not describe pagination limits or result volume, which keeps it from 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 primary behavior and scope lead, filters and inclusion set follow. Nothing is wasted and the trailing endpoint note costs negligible space.

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

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

There is no output schema, so the description carries the return-value burden and does explain that results include channel and latest message plus the sort order. Combined with the fully documented input schema, an agent has what it needs to invoke correctly; only pagination/volume behavior is left implicit.

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

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

Schema description coverage is 100% with 9 well-documented parameters, so the schema carries the parameter burden and baseline 3 applies. The description enumerates the filter axes (status, contact, assignee, channel, label, direction, update time) but adds no syntax or semantics beyond the enum/type hints already in the schema.

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

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

States a specific verb (List), resource (tickets/conversations), scope (visible to the token's user) and default ordering (newest activity first), which lets an agent distinguish it from trengo_list_ticket_messages or trengo_list_ticket_results. It stops short of naming the sibling that would be the alternative, so it is clear but not maximally 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?

The enumeration of filter dimensions implies when the tool is useful (browsing/filtering a ticket queue), and 'visible to the token's user' hints at the auth context. However it never states when to prefer this over trengo_list_ticket_results or trengo_get_ticket_details_report, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the underlying endpoint ('Trengo: GET /users'), which is minor context, but says nothing about pagination behavior or result size despite a page parameter existing.

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 purpose front-loaded and the endpoint mapping trailing. 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 simple read-only list tool with a fully documented schema and no output schema, the description covers what is returned (agents/users) and why it matters. It could note pagination limits but is otherwise sufficient.

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

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

Schema description coverage is 100% with only two parameters, so the schema already documents page and sort fully. The description adds no parameter detail, which is acceptable at this coverage level but earns no extra credit.

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 ('agents/users in the Trengo account'), and disambiguates that 'agents' and 'users' refer to the same entity. An agent can distinguish this from siblings like trengo_list_contacts or trengo_list_teams.

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 clause 'use their ids to assign tickets or filter' implies a downstream use case, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative for retrieving account members. Usage is 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 destructiveHint=true, so the mutation profile is covered. The description adds the closed-ticket precondition but says nothing about permissions, what state changes result, or what happens if the ticket is already open; the API endpoint restatement adds little behavioral value.

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 action and its precondition come first, with the endpoint as a secondary 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 single-parameter state-change tool with annotations covering the destructive hint and no output schema to explain, the description is nearly sufficient. Only the precondition context and error behavior (already-open ticket) are left implicit.

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

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

Schema description coverage is 100% and the single ticket_id parameter is documented in the schema as an integer id. The description adds no format, range, or sourcing detail beyond echoing {ticket_id} in the path, 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?

The description gives a precise verb+resource ('Reopen a closed ticket'), which is inherently distinguishable from the sibling trengo_close_ticket. It stops short of explicitly naming that sibling or any other alternative, so it is clear but not fully 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?

It states the precondition that the ticket must be closed, which implies when the tool is applicable, but gives no explicit when-to-use guidance, no exclusions, and does not route the agent to any alternative tool.

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

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

Annotations already declare destructiveHint=true; the description earns credit by explaining why — the message is delivered to the customer on email/WhatsApp/chat and is irreversible. This is meaningful behavior beyond the annotation. It does not cover permission/auth requirements or rate limits, 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?

Three sentences, front-loaded with the action and then the branching behavior and the irreversible-delivery warning. The API endpoint reference is a compact useful addendum. The all-caps emphasis is slightly heavy but functional.

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 5-param mutation tool with no output schema, the description covers the critical risk (irreversible customer-visible send) and both modes of operation. It does not need to explain return values, though it omits channel-specific pitfalls like HTML-only-for-email beyond what the schema states.

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

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

Schema description coverage is 100%, so all five parameters (including internal_note's dual meaning and email-only subject/attachment_ids) are already documented in the schema. The description restates internal_note's semantics rather than adding new syntax or format 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?

States a specific verb and resource ('Post a message on a ticket') and immediately splits the two modes of operation (internal note vs customer delivery), which is the key distinction an agent must make. It does not explicitly name a sibling, but the action is unambiguous against list_ticket_messages and the other ticket 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?

Gives clear context for the two branches: internal_note=true for agents only, otherwise delivered to the customer's channel. Adds the operative caveat 'cannot be recalled — confirm the text first'. No explicit alternative tool is named, so it stops short of a 5.

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

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

Annotations declare destructiveHint=true, so the safety profile is partly covered. The description goes beyond that by disclosing the key destructive behavior: 'user_ids / contact_ids replace the current sets', which tells the agent existing owners/leads will be overwritten. It also names the underlying endpoint. It does not cover auth requirements or what happens to omitted fields beyond the 'partially' cue.

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: the operation and its field breakdown are front-loaded, followed by the replace semantics and endpoint. No filler sentences.

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

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

No output schema exists, and the description gives enough to invoke correctly on a 6-parameter tool whose schema is fully documented. It omits only minor detail such as permission requirements and the exact response shape.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the replace-the-set semantics. The description restates the field groups and the replace behavior but adds no syntax, format, or constraint detail beyond the schema. Baseline 3 applies 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 and resource ('Partially update a board card') and enumerates the exact mutations supported: rename, move stage, set users/contacts. An agent can distinguish this from trengo_create_board_card purely from the description.

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

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

The word 'Partially' implies this is for incremental changes to an existing card, and the field list gives context for common operations. However, no explicit when-to-use vs. when-not guidance and no alternatives or prerequisites are named.

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

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

The destructiveHint=true annotation signals mutation, and the description adds real value beyond it by disclosing that contact_group_ids REPLACES the existing group set rather than merging it. It also names the underlying endpoint (PUT /contacts/{id}). It does not state permission requirements or confirm change reversibility, which keeps it from 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?

Three short, front-loaded sentences. The destructive REPLACES warning is placed prominently, and every sentence carries information with no filler.

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

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

For a small three-parameter update tool with annotations covering the safety profile and a fully documented schema, the description is sufficient for correct invocation. It omits only peripheral details like error behavior on invalid group ids.

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 three parameters are already documented, including the 'replaces the current groups' note on contact_group_ids. The description's REPLACES emphasis is helpful but largely duplicates the schema. Baseline 3 applies.

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

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

States a specific verb ('rename', 'set') and resource ('contact', 'contact groups'), so the agent knows exactly what the tool mutates. It is distinguishable from trengo_get_contact and trengo_create_contact by implication, though it never names a sibling explicitly.

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

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

The 'and/or' phrasing implies the tool is used when renaming or reassigning groups, which gives usable context. However, there is no explicit when-not guidance or mention of alternatives such as trengo_create_contact for new records.

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