Trengo MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description's claim that the action is 'reversible by reassigning' is genuinely additive context that softens the destructive flag without contradicting it. It does not, however, say what happens to the previous assignee, whether notifications fire, or what permissions are required.

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 plus the underlying endpoint; the core action is front-loaded and no sentence is filler. The API path is arguably extra but is short and useful for mapping to Trengo's REST surface.

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 and only a destructiveHint annotation, the description covers the essentials: what changes, the two assignment modes, the optional note, and reversibility. Missing only side-effect detail such as notifications or prior-assignee handling.

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

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

Schema description coverage is 100%, including the conditional 'required when type is team/user' notes, so the schema carries the parameter burden. The description only restates that the note is optional and that the target may be a user or team, adding nothing beyond what the schema already says.

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 ('assign') plus resource ('ticket') with the target dimension named (user or team) and the optional note acknowledged. It is clearly distinct from siblings like trengo_close_ticket or trengo_reopen_ticket, though it never names an alternative to contrast against.

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

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

Usage is implied by the verb and by the 'reversible by reassigning' hint, but there is no explicit guidance on when to assign versus closing, updating, or replying to a ticket, and no stated prerequisites such as needing to resolve a user_id/team_id first.

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

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

Annotations declare destructiveHint=true, and the description usefully adds that the operation is reversible via trengo_reopen_ticket, which materially softens the destructive signal. It still omits side effects such as notifications to the contact or SLA/status changes, so it is not fully transparent.

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

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

Three tight clauses, front-loaded with the action and followed by the optional parameter, the undo path, and the 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?

Both parameters are documented in the schema, no output schema exists, and reversibility plus the result-listing dependency are covered. The remaining gap is operational context (what closing actually changes on the ticket), which is minor for a two-parameter action.

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 discoverability value by pointing at trengo_list_ticket_results as the source of valid ticket_result_id values. The required ticket_id needs no further explanation.

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 ('Close a ticket') plus an optional modifier ('optionally applying a ticket result'), which cleanly separates it from sibling mutations like trengo_reopen_ticket or trengo_assign_ticket. The API endpoint is also given, pinning the exact operation.

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?

Routes the agent to two relevant siblings: trengo_list_ticket_results for obtaining a valid result id, and trengo_reopen_ticket for undoing the action. It does not spell out when NOT to close (e.g., preconditions like ticket state), so it stops short of full when/when-not guidance.

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

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

With destructiveHint=true already declared, the safety profile is partly covered, and the description adds the underlying REST call (POST /boards/{boardId}/cards) for API-level transparency. However, it says nothing about permissions required, side effects, whether the card triggers notifications, or rate limits, which would be valuable for a mutation tool.

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 action, with no filler. The trailing endpoint reference is slightly redundant for an agent that already has the tool interface, but it earns its place as API context.

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 create operation with no output schema and no annotations covering returns, the description should indicate what comes back (e.g., the new card or its id) and whether required fields like stage must pre-exist. It covers the resource and ID location but leaves those gaps for an agent to discover.

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 still earns above it by explaining that board_id lives in the board's URL, which the schema's bare 'The board id.' does not convey. It adds no clarifying semantics for stage_id, name, or description beyond the schema.

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

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

The description gives a specific verb and resource ('Create a card... in a stage of a Trengo board') and clarifies with an example that a card can be a deal or task. It is easy to distinguish from siblings like trengo_create_ticket or trengo_create_contact, though it never explicitly contrasts itself with them.

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

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

There is no guidance on when to use this tool versus alternatives such as trengo_create_ticket, nor any prerequisites stated. The only actionable hint is where to find the board id ('in the board's URL'), which is a locator tip rather than usage guidance.

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

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

Annotations only supply a title and destructiveHint=true, so the description carries most of the behavioral burden. It discloses the channel-dependent identifier rule and the underlying REST endpoint, but says nothing about duplicate handling, idempotency, permission requirements, or side effects — a notable gap for a mutating call flagged as 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?

Three short sentences, front-loaded with the action and the key semantic rule. The trailing endpoint reference ("POST /channels/{channel_id}/contacts") is useful for developers but is the least essential element for an agent selecting a tool.

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 3-parameter, no-output-schema mutation tool the description covers the essentials (what, where, identifier semantics), and return values need not be explained. However, it omits any hint about behavior on duplicates or failure, which matters given the destructiveHint 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 already 100%, which sets the baseline at 3, but the description genuinely adds meaning beyond the schema by mapping identifier types to channel types (email channel → email address, WhatsApp/SMS/voice → phone number). The schema's own identifier text is vaguer about which channels map to which format.

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

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

States a specific verb and resource ("Create a contact on a channel") plus the scope constraint that the contact belongs to a channel. This clearly distinguishes it from siblings like trengo_get_contact and trengo_update_contact, though it never names those alternatives 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 description implies usage through context but gives no explicit when-to-use, when-not, or alternative (e.g., import vs. single-create, or updating an existing contact instead). An agent must infer from the verb alone that this is the single-record creation path.

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 provide only destructiveHint=true, so the description carries most of the load and does add a genuinely useful behavioral fact: no customer-facing message is emitted on creation. It does not discuss permissions, whether the having an existing contact is validated, or the failure behavior if the contact/channel is invalid.

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 core action and the critical 'nothing is sent yet' caveat front-loaded, plus the underlying 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 3-parameter create tool with no output schema and fully documented params, the description covers what an agent needs to act correctly. It leaves the return value (e.g. the new ticket id) unstated, which is a minor gap given no output schema exists.

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 all three parameters, so the schema already documents subject, channel_id, and contact_id. The description only reinforces that the contact must pre-exist; it adds no format, ID-sourcing, or defaulting detail beyond the schema.

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

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

States a specific verb and resource ('Open a new ticket') and adds the scoping constraint that the contact must already exist and a channel is involved. An agent can distinguish this from trengo_send_ticket_message or trengo_create_contact 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?

Explicitly explains the relationship with trengo_send_ticket_message, clarifying that creating a ticket alone sends nothing to the customer. It does not name when-not-to-use or alternatives for ticket creation itself (e.g. board cards), 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 safety is covered; the description adds genuinely non-obvious behavioral detail by disclosing that response/resolution averages are computed both with and without business hours. That is real context beyond the structured fields, though it says nothing about pagination behavior or result 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?

A single dense sentence that front-loads the subject and only then enumerates the metric set, with the endpoint tacked on at the end. No filler or repetition.

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 must carry the return-value burden, and it does by naming the metric families the report contains. It is slightly thin on the fact that all filters are optional and on pagination semantics, but nothing critical for invoking the tool 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 all seven filters (page, date pair, team/user/label/channel ids) are already documented in the schema, making 3 the baseline. The description adds no format guidance or interaction between filters beyond the period framing.

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

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

States a specific resource (per-agent performance) and enumerates the metrics returned — messages sent, notes, tickets assigned/closed, first response and resolution times — plus the underlying endpoint. It does not differentiate itself from the two sibling reporting tools (trengo_get_reporting_metrics, trengo_get_ticket_details_report), which keeps it from 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 phrase 'over a period' and the reporting framing; there is no explicit when-to-use statement and no routing to the sibling reporting tools. An agent can infer this is the per-agent analytics call, but nothing resolves the overlap with trengo_get_reporting_metrics.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing the shape of the payload (name, email, phone, custom field data) and that notes are included only on request. It says nothing about error behavior for a nonexistent id, rate limits, or authentication, which is the remaining gap.

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

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

One sentence plus an endpoint reference; the returned-field list and the optional-notes flag are front-loaded with no filler. Nothing is redundant.

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

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

With no output schema, the description usefully describes the return payload, and annotations cover the safety profile, so the essential information is present for a simple two-parameter getter. Only not-found/error semantics are left unaddressed.

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, and the baseline is 3. The phrase 'optionally with notes' loosely mirrors include_notes but adds no format, default, or cost detail beyond the schema.

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

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

The description gives a specific verb and resource ('Fetch one contact') and enumerates the returned fields, so the agent knows exactly what the tool does. It implicitly separates itself from trengo_list_contacts by saying 'one contact', but never names a sibling tool 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as trengo_list_contacts for bulk retrieval or trengo_get_ticket_details_report for related lookups. Usage is only implied by the tool name and purpose.

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

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

With readOnlyHint=true the safety profile is already covered, so the description earns credit for going beyond it: it discloses exactly what is returned (original HTML body plus headers, including Message-ID) and the applicability restriction on message type. It stops short of noting permissions or behavior for non-email messages, keeping it at a 4 rather than 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 sentences, front-loaded with the payload the agent gets and then the constraint and endpoint. The trailing "Trengo: GET /tickets/{ticket_id}/full_email_messages/{message_id}." is largely redundant detail, slightly diluting an otherwise tight description.

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 correctly carries the burden of describing the return payload (HTML body, from, to, subject, Message-ID). Combined with the readOnly annotation and fully documented parameters, an agent has enough to call this correctly; only the error/fallback path for non-email messages is unstated.

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

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

Schema description coverage is 100% and both identifiers are documented there with type and range constraints. The description only restates that there is one ticket and one message involved, adding no format or sourcing detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (the full email behind one message of a ticket), and enumerates the payload fields (HTML body, from, to, subject, Message-ID) along with the constraint that the message must be an email message. That constraint implicitly separates it from the generic trengo_list_ticket_messages, but no sibling is named outright, so it falls short of a full 5.

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

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

"The message must be an email message" is a precondition that tells the agent when this tool does not apply, which is real usage value. However, it never names the fallback tool or explains where to get the message id from, so the agent must infer the alternative path.

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 useful context about aggregation, metric names, units in seconds, and filter axes, but it does not mention the required start/end date pairing constraint or any pagination/rate-limit 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 sentences with the purpose, metric list, filters, and endpoint front-loaded. There is no redundant or wasted text, and the structure makes the key information immediately scannable.

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 tool with 7 parameters and full schema coverage, the description adequately explains the aggregate purpose and available metrics. However, with no output schema it does not describe the response shape, and it omits the start/end date pairing requirement, leaving modest gaps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including enum options, date pairing, and required metrics. The description mostly repeats the metric names and filter axes, adding only the 'seconds' unit, which is a minor gain.

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'), then enumerates the exact metric types and filter dimensions. It does not distinguish itself from sibling reporting tools such as trengo_get_agent_performance or trengo_get_ticket_details_report, 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The filter dimensions describe parameter behavior rather than selection criteria, leaving usage context implicit at best.

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

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

Annotations declare readOnlyHint=true, so the safety profile is covered; the description adds beyond that by disclosing the returned columns and the business-hours vs non-business-hours timing distinction, plus the keyset-pagination behavior for large accounts. It does not mention rate limits or result caps, so it is not fully 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?

Two dense sentences, front-loaded with what the report returns before filters, sorting, and pagination. Efficient, though the filter list is somewhat run-on and the endpoint suffix adds little for an agent.

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

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

With 15 optional parameters, no output schema, and only a readOnlyHint annotation, the description compensates well by naming the returned columns and the pagination strategy. It is close to complete, missing only edge details like maximum page size or date-range pairing constraints 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 every parameter is already documented, including the 'give it together with its pair' date-pairing rule and the keyset-cursor explanation. The description largely restates the filter/sort surface provided by the schema, so the 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 ('Per-ticket reporting rows') and enumerates the returned dimensions (status, assignee, labels, first reply, first/first-resolution/total resolution times). The phrase 'Per-ticket reporting rows' cleanly distinguishes it from sibling aggregate tools like trengo_get_reporting_metrics and trengo_get_agent_performance.

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 real operating context: which filters are available, that you sort by a timing metric, and specifically that huge accounts should page with start_after_ticket_id instead of page. It stops short of naming sibling tools or stating when this report is the wrong choice versus the metrics/agent-performance reports.

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, so the description's main added value is that results are account-scoped and their ids are consumed by trengo_update_contact. It discloses nothing about pagination behavior despite the page parameter, nor about result ordering or 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?

A single front-loaded sentence carries the core meaning, with the API endpoint appended as compact reference. No repetition of the title and nothing that fails to earn its place.

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

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

For a trivial read-only list tool with a fully documented single parameter and no output schema, the description plus annotation covers what an agent needs: what it returns (contact groups), that it is account-wide, and how the ids are used. Only return-field detail 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?

One parameter with 100% schema description coverage ('Page number (1-based). Omit for the first page.'), so the schema fully documents it. The description adds no pagination or page-size context beyond that, which is the baseline expectation 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 ('List the contact groups in the account'), which clearly separates it from siblings like trengo_list_contacts, trengo_list_labels, and trengo_list_teams. Scope is implied (account-wide) but the description stops short of contrasting itself with the other list_* tools beyond the resource noun.

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 downstream usage: 'use their ids with trengo_update_contact', which tells the agent why and when to call this tool (to obtain group ids for a contact update). It lacks any when-not guidance or mention that other list tools exist, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the backing endpoint ("Trengo: GET /contacts"), which is marginal; it says nothing about pagination flow or result volume beyond what the schema's page param 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?

One short sentence covering both modes, front-loaded with the primary action. Nothing extraneous; the endpoint note is a single compact clause.

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-param, read-only list tool with a fully documented schema and no output schema, the description is adequate but thin. It omits any hint of result shape (e.g. that include_last_interaction enriches each contact) or pagination expectations.

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 fully documented in the schema. The description's mention of matching on name, email, and phone merely restates the term parameter and adds no syntax or format 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 (list) and resource (contacts), plus the searchable fields (name, email, phone). It is distinguishable from trengo_get_contact by being plural/list-oriented, though it never names that 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 two modes (list vs search by name/email/phone) are implied by the single sentence, so an agent can infer that supplying a term triggers search. There is no explicit statement of when to prefer this over trengo_get_contact or how it relates to other list tools.

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 adds useful scope (the three entity types whose fields are returned) and the underlying endpoint, but says nothing about result size, pagination behavior, or whether paginated results require iterative calls even though a page parameter exists.

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 no filler. The trailing 'Trengo: GET /custom_fields.' is mildly redundant metadata, but it is compact and does not obscure the core statement.

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 complete parameter coverage and annotations carrying the safety profile, the essentials are present. However, with no output schema the description could reasonably indicate what the returned field objects look like or that results are paginated, which it does not.

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 baseline is 3. The description adds no pagination or default-page semantics beyond what the schema already states.

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), plus the scope of where those fields apply: tickets, contacts and profiles. This is clearly distinguishable from sibling list tools such as trengo_list_labels, trengo_list_teams or trengo_list_users, though it never names an alternative 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 description only says what the tool returns; it gives no conditions for when to call it, no prerequisites, and no guidance on when another sibling (e.g. trengo_get_contact or trengo_get_ticket_details_report) would better answer the need. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /labels) and the business purpose of the data, but says nothing about pagination behavior or result size even though a page parameter exists.

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 action and resource, with the purpose clause and endpoint reference appended. No redundant or filler text.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers what the tool returns and why it matters. Minor gap: it never mentions pagination for a tool that exposes a page parameter.

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% — the single page parameter is fully documented in the schema. The description adds no syntax, defaults, or format 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 and resource — 'List the ticket labels (tags) in the account' — which is unambiguous and naturally distinct from siblings like trengo_list_teams or trengo_list_contacts. It does not explicitly differentiate itself from any sibling, but no sibling overlaps this resource, so the risk is low.

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?

'For filtering tickets and reports' implies why labels exist and when an agent might reach for them, but there is no explicit when-to-use statement, no prerequisites, and no named alternative. Usage is inferred rather than stated.

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

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

The annotations already declare readOnlyHint=true, correctly signaling a safe read operation. The description adds only minor context (saved/canned replies, endpoint mapping) and does not disclose return format, pagination, or any rate-limit behavior beyond what annotations provide.

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

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

The purpose and optional filter are front-loaded in a single efficient sentence, with the endpoint mapping appended as useful metadata. There is no redundant or filler language.

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 enum parameter and no output schema, the description is nearly complete: it states what is listed, the optional filter, and a use case. It could mention pagination or result cardinality, but no critical information for correct invocation is missing.

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

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

Schema description coverage is 100%, so the single 'type' parameter and its enum values are already fully documented. The description restates the optional filter in prose ('messaging or email ones') but adds no syntax or format detail beyond the schema.

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

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

The description gives a specific verb ('List'), resource ('saved quick replies (canned responses)'), optional filter scope, and maps to the underlying endpoint 'GET /quick_replies'. It clearly distinguishes this tool from the many other list operations by 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?

It provides a clear context ('useful for drafting consistent answers') but does not include explicit when-not conditions or alternatives. For a simple read-only list with no close sibling to disambiguate, this is adequate context without 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful intent (ids used for assignment) and an endpoint hint, but says nothing about pagination behavior, result size, or ordering beyond what the schema and annotations provide.

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

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

One tight sentence front-loads the action and intent, with the endpoint reference trailing as optional lookup info. No wasted words.

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?

Complete for a simple read-only list with one optional parameter and annotations covering safety. Minor missing detail on pagination and result shape, but the output is straightforward and no output schema exists that would carry that burden.

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%: the single page parameter is fully documented in the schema with 1-based semantics and omit-for-first-page guidance. The description adds no parameter information, 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 teams) and adds downstream intent (use ids to assign tickets to a team). This distinguishes it from sibling list tools like trengo_list_users and trengo_list_contact_groups, which return different resources.

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?

Provides clear context: this is for fetching team ids, which feed into ticket assignment. It does not, however, explicitly name trengo_assign_ticket as the paired alternative or state when not to use this tool.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real behavioral context beyond the annotation: the response mixes inbound, outbound and internal-note messages and attributes each to a contact or agent. It does not mention pagination behavior, which is the main remaining gap.

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

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

A single front-loaded sentence that names the scope and the returned content, followed by the API 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?

For a two-parameter read tool with no output schema, the description covers what the tool returns (message kinds plus sender attribution) well enough to call it correctly. Only pagination/ordering expectations are left implicit, which is a minor omission.

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

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

Schema description coverage is 100%, so both ticket_id and page are already documented in the schema. The description adds nothing about identifier format or pagination, so the baseline of 3 applies.

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

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

States a precise verb (List) and resource (messages of one ticket), and even enumerates the message kinds returned — inbound, outbound and internal notes. It is easily distinguished from sibling list_tickets (which lists tickets) and send_ticket_message (which writes one).

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

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

Usage is only implied: an agent infers this is the tool for reading a ticket's conversation thread, but there is no explicit when-to-use statement, no prerequisites, and no alternative named. Adequate but with a clear gap in 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 safety profile is covered. The description adds useful domain context about what the results represent, but says nothing about pagination behavior or the shape of the returned list, so it adds only modest value beyond the annotations.

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

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

Two tight sentences: definition of the resource first, endpoint reference last. No filler, nothing redundant, and the most important information (what ticket results are) is front-loaded.

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

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

For a simple read-only list endpoint with a one-parameter schema and no output schema, the description supplies enough to call it correctly and understand the values returned. Minor gap: no hint about pagination limits or result volume, and no pointer to the close-ticket tool that consumes these values.

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 1-based paging and that it can be omitted. The description adds no paging or format nuance, which is the correct 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?

States a specific verb (List) and resource (ticket results), and then defines the resource in domain terms ('closing outcomes, e.g. Resolved, Sale') so an agent understands what these are without opening anything else. This clearly distinguishes it from generic list siblings like trengo_list_labels 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 phrase 'that can be applied when closing a ticket' implies the usage context (paired with the close-ticket flow), but there is no explicit when-to-use, when-not, or named alternative. An agent can infer the scenario but gets 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?

readOnlyHint=true already covers the safety profile, so the description earns credit for adding behavior beyond annotations: the results are scoped to the token's user, they are ordered by newest activity by default, and each row carries channel and latest message. It stops short of disclosing pagination semantics or whether results are capped per page.

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

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

Three tight sentences with the core purpose and scoping front-loaded, then filters, then the endpoint reference. The trailing 'Trengo: GET /tickets.' adds little for an agent choosing a tool, but overall there is very little waste.

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

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

For a 9-parameter, all-optional read tool with no output schema and a readOnly annotation, the description covers purpose, scoping, default sort, and filter axes. Return-value detail is not required given no output schema, though pagination behavior and any per-page limits remain unaddressed.

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% across all 9 optional parameters, so the schema already fully documents filters, enums, and defaults. The description's filter list ('status, contact, assignee, channel, label, last message direction or update time') maps onto those parameters without adding format or syntax detail beyond them, so the baseline 3 applies.

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

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

States a specific verb and resource ('List tickets (conversations)'), plus the visibility scope ('visible to the token's user'), default ordering, and the fields returned. This clearly separates it from write siblings like trengo_create_ticket or trengo_close_ticket, but it never contrasts itself with the closest read siblings such as trengo_list_ticket_results or trengo_list_ticket_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?

The description enumerates available filters but gives no when-to-use or when-not-to-use guidance and names no alternative tool. An agent cannot tell from this text why it would pick trengo_list_tickets over trengo_list_ticket_results or trengo_get_ticket_details_report.

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

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

Annotations already declare readOnlyHint=true, and the description only restates this via "GET /users". It adds nothing about pagination behavior, result volume, or account scoping constraints that would go beyond the structured metadata.

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

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

Two short sentences with the purpose and usage front-loaded, no padding. The trailing "Trengo: GET /users." is mildly redundant but harmless and compact.

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

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

For a simple read-only list tool with full schema coverage and safety covered by annotations, the description supplies enough to call it correctly. Pagination semantics live in the schema, so nothing critical is missing, though no output-shape hint is 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 description coverage is 100% and both parameters (page, sort) are fully documented in the schema, so the baseline is 3. The description adds no format or default guidance for page/sort beyond what the schema already supplies.

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

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

States a specific verb+resource ("List the agents (users)") and clarifies the agent/user naming overlap, which helps separate it from contact- or team-listing siblings. It does not explicitly name a sibling it is an alternative to, 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?

"use their ids to assign tickets or filter" gives clear downstream context for why an agent would call this rather than something else. There are no explicit when-not conditions or named alternatives, which keeps it out of 5 territory.

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 and a title, so the safety bar is lower. The description adds the useful precondition that the ticket must be closed and identifies the underlying endpoint, but says nothing about side effects (status change, notifications), permissions, or failure behavior when the ticket is not closed.

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, action and endpoint, with the core purpose front-loaded. Nothing redundant or padded.

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

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

For a one-parameter state-change tool with no output schema, the description covers what an agent needs to call it: the target resource, the precondition, and the endpoint. It is only slightly thin on post-call behavior, which the annotations partially cover.

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?

With a single parameter and 100% schema description coverage, the schema already documents ticket_id fully. The description adds no format, range, or sourcing detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Reopen a closed ticket') and the precondition (must be closed), which implicitly separates it from siblings like trengo_close_ticket. It does not name an alternative tool explicitly, so it falls just short of the top mark.

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 'a closed ticket' implies when the tool applies, but there is no explicit when-to-use guidance, no statement of what to do instead (e.g., close_ticket, send_ticket_message) and no exclusions. Usage must be inferred.

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?

Goes well beyond the destructiveHint annotation by disclosing that the non-internal message is delivered to the customer's channel and cannot be recalled, and that text should be confirmed first. This is exactly the consequence information an agent needs before an irreversible write.

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

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

Front-loads the core action, then the branching behavior, then the endpoint. The ALL-CAPS emphasis is slightly shouty but functionally directs attention to the irreversible path; overall the passage is tight and earns its place.

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

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

For a write tool with no output schema and only a destructiveHint annotation, the description supplies the missing risk context (external delivery, irreversibility, channel scope) and the endpoint. Nothing essential for correct invocation is absent.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including internal_note's true/false semantics. The description reinforces the internal_note consequence but adds no new syntax or format detail beyond the schema, matching the baseline.

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

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

States a specific verb (Post) and resource (a message on a ticket), which is unambiguous against siblings like trengo_list_ticket_messages (read) or trengo_assign_ticket. An agent can identify the operation 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?

Explicitly explains the internal_note=true vs default branch, effectively telling the agent when to use which mode. It does not, however, contrast with alternatives such as listing messages first, so it omits an exclusion/alternative comparison.

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; the description earns credit for explaining WHY — user_ids/contact_ids 'replace the current sets' rather than appending, which is the key destructive behavior an agent must not get wrong. It stops short of stating auth/permission needs or what the response contains.

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 plus the endpoint reference; the mutation scope leads, the dangerous replace semantics follow, and the raw API path is relegated to the end. 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 6-param partial-update tool with no output schema and only a destructiveHint annotation, the description covers mutability scope, field mapping, and replacement semantics. It omits whether unmodified fields are preserved and what the call returns, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents each field including the 'replaces the set' note. The description adds a semantic mapping (name=rename, stage_id=move, users=owners, contacts=leads) but no format or constraint details 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 ('partially update') and resource ('board card'), then enumerates the three mutable aspects (name, stage, users/contacts) and names the backing endpoint. An agent can distinguish this from trengo_create_board_card 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?

'Partially update' implies the use case (modifying an existing card rather than creating one), which is meaningful context against the create sibling. However, there is no explicit when-not guidance, no prerequisites, and no statement about which fields can be omitted versus which must be supplied.

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

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

With only destructiveHint=true in annotations, the description adds real context: it discloses that contact_group_ids overwrites rather than appends, which explains the destructive flag, and that updates are partial ('and/or'). It omits auth requirements and error behavior, keeping it out of the top band.

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, front-loaded sentences with the overwrite warning in caps where it matters most. The trailing 'Trengo: PUT /contacts/{id}' is minor filler that an agent already has from the tool identity, but nothing else 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 3-parameter update with full schema coverage and no output schema, the description covers what matters: what can change and the destructive group semantics. Only prerequisites and failure behavior are unaddressed, which are small gaps 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 all three parameters are already documented in the schema, including the group-replacement note. The description largely restates that verbatim, adding only emphasis and the mutual optionality of name/contact_group_ids; 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 ('Rename a contact and/or set the contact groups it belongs to'), naming the exact fields the tool can change. This clearly separates it from siblings like trengo_create_contact and trengo_get_contact 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 implicit: the 'and/or' phrasing tells the agent at least one of the two updateable fields is expected, and the REPLACES warning signals destructive group reassignment. However, it never states when to reach for this tool over create/get, nor any prerequisite such as the contact having to exist.

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