HappyFox MCP by usefulapi

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

Annotations only supply destructiveHint=true and a title, so the description carries most of the burden. It adds meaningful context the annotations don't: the note is internal-only, and the call can also mutate status, priority, assignee, due date and tags — a non-obvious side effect that helps explain the destructive hint. It doesn't explain reasons for the destructive classification or reversibility.

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 purpose front-loaded before the side effects. The trailing REST endpoint reference is marginally useful context but not strictly necessary for an agent selecting the 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 12-parameter mutation tool with a nested custom_fields object, the schema covers parameter detail comprehensively and there is no output schema to explain. The description supplies purpose and side effects; it could note that mutating options are best avoided when merely annotating, but overall it is complete enough to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly (including the alert enum pattern and custom_fields conventions). The description's mention of alerting/status/priority/assignee/due date/tags merely summarizes existing schema fields without adding new syntax or meaning; 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+resource ('Add an internal note') and clarifies scope with 'never sent to the contact', which effectively distinguishes it from the sibling happyfox_add_staff_reply. It stops short of naming that sibling explicitly, so differentiation is implicit 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 description conveys that this is an internal-facing note with optional side effects, which implies when you'd use it (staff-only context) versus a customer reply. However, it never states prerequisites or explicitly names the alternative tool, leaving usage 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?

Annotations supply only destructiveHint=true, so the description carries the load and does it well: it discloses the customer-facing email side effect and its default-off behavior, the no-message property-only mode, and the compulsory-custom-field prerequisite for closing. These are the highest-risk, least-obvious behaviors of this mutation.

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

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

Four dense sentences, front-loaded with the core action and the most surprising constraint (email gating) placed early. The trailing REST endpoint line is harmless but not something an agent needs to select or invoke the 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 16-parameter destructive mutation with no output schema, the description covers the important behavioral prerequisites and side effects. It omits anything about return payload, error conditions, or partial-update behavior, but with no output schema that burden is lower.

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 update_customer, custom_fields, and the completion requirement. The description reinforces update_customer and the closing constraint but adds little syntax or format detail beyond what the schema provides, matching the baseline 3.

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+resource ('Add an agent reply to a ticket') and immediately broadens it to the property-mutation capability (status, priority, assignee, due date, tags), so the dual nature of the tool is unmistakable. It does not, however, explicitly distinguish itself from close siblings such as happyfox_add_private_note or happyfox_update_ticket_tags, leaving that contrast to inference.

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

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

It gives real decision context: the contact is emailed ONLY when update_customer is true (default false), and with no message the call degrades to a pure property update. It also warns that moving to a completed status may require compulsory custom fields. It stops short of naming an alternative tool for the internal-note case.

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; the description adds the far more actionable detail that any custom field NOT passed is reset, which explains why the operation is destructive. That is exactly the kind of hidden side effect an agent needs before calling.

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 key risk (field reset) front-loaded ahead of the alternative tool and endpoint. The trailing 'HappyFox: POST /api/1.1/json/users/' adds little for an agent and is the only mildly wasteful element.

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 annotations covering only destructiveness, the description supplies the identity key, the destructive side effect, and the routing alternative. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: email acts as the identity key for the upsert, and the reset behavior governs how custom_fields must be populated. The custom_fields entry-format detail lives in the schema, so this is additive rather than redundant.

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

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

States a specific verb+resource ('Create a contact') and immediately clarifies the non-obvious upsert semantics keyed on email. It also names the sibling it should not be confused with (happyfox_update_contact), so an agent can separate the two 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?

It explicitly names the alternative ('use happyfox_update_contact to edit an existing contact') and explains the email-keyed create-or-edit condition. The guidance is slightly self-inconsistent, since the tool itself updates existing contacts, leaving some ambiguity about when update_contact is genuinely preferred over this call.

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

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

Annotations only declare destructiveHint=true, so the description carries real weight: it discloses the side effect that a new contact is created when the email is unknown, and the constraint that the category must be public. It omits auth requirements, rate limits, and any note on duplicate-ticket 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, front-loaded with the core action and the contact-creation caveat, with no padding. The trailing API endpoint ("POST /api/1.1/json/tickets/") is low-value detail for an agent choosing a tool, which keeps it from a perfect score.

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 creation tool with only a destructiveHint annotation and no output schema, the description is thin. Most critically, it never says what is returned (presumably the new ticket id), which an agent likely needs for follow-up calls like happyfox_update_ticket_tags.

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's parameter claims (public category, text-or-html requirement) largely restate what the schema already documents, adding little semantic value 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") plus the acting party ("on behalf of a contact"), and the parenthetical about auto-creating a new contact is a meaningful scope detail. It is clearly distinct from reply-oriented siblings like happyfox_add_staff_reply and happyfox_add_private_note, 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?

Gives prerequisites (needs a public category id, subject, and text or html message), which is exactly what an agent needs before invoking. It also pre-answers the practical question of whether to call happyfox_create_contact first. It stops short of stating when not to use it or naming alternatives for ticket creation paths.

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. The description goes further by naming the concrete data returned (phone numbers, contact groups, ticket counts, custom fields) and the backing endpoint GET /api/1.1/json/user/<id or email>/, which helps an agent anticipate payload shape in the absence of an output schema.

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

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

Two tight sentences with the identity/scope constraint front-loaded before the returned-fields list. The raw endpoint tail is slightly redundant but compact, so it doesn't materially dilute the definition.

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 read tool with annotations covering safety and a fully documented parameter, the description is complete enough: it discloses returned fields despite no output schema. Minor gap in not describing error/not-found behavior keeps it from a 5.

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

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

Schema coverage is 100% and the single parameter's description already documents the id-or-email format, so the description adds no meaning beyond the schema. Baseline 3 is appropriate 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?

Specific verb (Fetch) plus resource (a contact) and it explicitly enumerates returned artifacts — phones, contact groups, ticket counts, custom fields. The singular scope plus the id-or-email identification distinguishes it from the sibling happyfox_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?

"by id or by email address" implies the appropriate usage context for a single-record lookup, and the sibling list_contacts makes the single/list split inferable. However, it never explicitly states when to prefer this over list_contacts or what happens on a not-found id.

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

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

The readOnlyHint annotation already declares the safety profile, so the bar is lower. The description usefully adds that member contacts are returned alongside the group (not just the group record) and cites the REST endpoint, but it says nothing about pagination, error behavior, or authentication beyond what the annotation implies.

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

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

Two tightly packed sentences, front-loaded with the behavioral fact (member contacts included) before the endpoint reference. No filler or redundancy.

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

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

For a one-parameter read with no output schema, the description is nearly complete: it tells the agent what is returned (group plus members). It could go slightly further on the response shape or on what happens for an invalid id, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so the single required contact_group_id is fully documented in the schema. The description's '<id>' placeholder mirrors the same information without adding format constraints or bounds. 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 a contact group') and clarifies scope with 'and its member contacts', which distinguishes it from the sibling happyfox_list_contact_groups (plural listing). It stops short of naming that sibling explicitly, but the singular framing makes the retrieval-one-vs-list-many distinction inferable.

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

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

Usage is implied rather than stated: fetching by id is the obvious trigger. There is no explicit when-to-use guidance and no mention of alternatives such as happyfox_list_contact_groups or happyfox_get_contact, so the agent must infer the routing itself.

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

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

The readOnlyHint annotation already declares this is a safe read, so the description only needs to add context. It does add value by enumerating the exact counts returned and citing the underlying API endpoint, but says nothing about authentication, rate limits, or whether the report must be pre-saved with data populated.

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 payload contents front-loaded and no filler. The trailing API endpoint line is mildly redundant but small.

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 correctly takes on the burden of describing the return shape by listing the count categories. The main gap is sibling differentiation from happyfox_get_report_tabular_data, which is not addressed.

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 report_id parameter is fully documented in the schema, including the tip to obtain it from happyfox_list_reports. The description's '<id>' reference adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb (summary counts) and resource (a saved report) and enumerates the concrete counts returned. It is clear what the tool does, but it never mentions the sibling happyfox_get_report_tabular_data, so an agent cannot tell the two report tools apart from the description alone.

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 versus alternatives such as happyfox_get_report_tabular_data or happyfox_list_reports. Usage must be inferred from the word 'summary' and the returned counts.

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's added value is the per-row column list (display_id, subject, status, assignee, due date) and the pagination disclosure. It does not cover ordering, total counts, or page bounds, so it stops short of a 5.

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

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

One compact sentence front-loads the resource, granularity, and returned fields, then tacks the API path on at 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?

With no output schema, naming the row columns is the right compensation. Missing only minor operational detail such as ordering or how to detect the last page, which the schema's size/page fields partly imply.

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, size, and report_id are already documented with defaults and ranges. The description only echoes pagination without adding format or constraint detail, 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 resource and shape: 'the tabular view of a saved report — one row per ticket', with the returned columns enumerated. This distinguishes it implicitly from happyfox_get_report_summary, though the sibling is never named.

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 'tabular view of a saved report'; there is no explicit statement of when to pick this over happyfox_get_report_summary or happyfox_list_reports. Adequate but leaves the choice 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?

With readOnlyHint=true already covering the safety profile, the description still adds real behavioral value: it discloses that the response includes private notes, property changes, and attachments whose links expire in 5 minutes. That expiry caveat is the kind of non-obvious trait an agent would otherwise miss; it stops short of describing error behavior for an unknown ticket.

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

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

Front-loaded with the verb and the richest detail (what the conversation contains), with the endpoint appended for reference. Dense but each clause earns its place; the raw URL is slightly redundant but harmless.

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

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

There is no output schema, so the description carries the return-value burden and does so by enumerating the returned fields. The 5-minute attachment-link expiry is a valuable operational detail; only error/edge behavior for a missing ticket is 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%, and the ticket_number schema already spells out the numeric-id vs prefixed-display-id distinction. The description adds no syntax or format detail for show_cf_changes, 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 (Fetch) and resource (a ticket) and enumerates the payload scope — conversation, status, priority, contact, assignee, custom fields, SLA breaches. This clearly separates it from the sibling list_tickets, which would return many tickets rather than one full conversation.

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 its use case (retrieve the full detail of a known ticket, referenced by ticket_number) but never states when to prefer it over happyfox_list_tickets or names any prerequisite such as needing the numeric id. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying HTTP endpoint (GET /api/1.1/json/categories/), which reinforces the read-only nature, but says nothing about pagination, ordering, or the shape 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?

Two short sentences with no waste: the purpose and the returned identifier are front-loaded, and the endpoint reference trails as supporting 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 zero-parameter list operation with readOnlyHint set and no output schema, the description covers what it returns (categories with ids) and why it matters. Only minor gaps remain around result ordering or size.

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

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

The tool takes zero parameters, so there is nothing for the description to document beyond the schema. The baseline for a parameterless tool applies, and the description correctly does not invent parameters.

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 ticket categories') and disambiguates the term by equating categories with 'queues', plus notes that ids are returned. It does not explicitly contrast itself with any sibling tool, 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?

Gives concrete usage context — 'needed to create a ticket or filter tickets' — which tells the agent when this lookup is worth calling. It stops short of naming alternatives or exclusions, but the contextual trigger 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 establishes the safe-read profile, and the description adds value beyond it: the specific fields returned (id, type, choices, required flag), the 'c-cf-<id>' identifier convention callers must use, and the backing endpoint GET /api/1.1/json/user_custom_fields/. With no output schema, this return-shape disclosure is genuinely useful.

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: purpose + returned fields, then the id convention, then the endpoint. Front-loaded with the verb and resource, 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?

For a parameterless read with no output schema, the description covers purpose, returned fields, id format, and endpoint. Minor gaps remain (pagination, ordering, empty-result behavior), but nothing essential to correct invocation is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless definition is 4. The c-cf-<id> note pertains to identifiers returned, not to invocation inputs.

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 contact custom fields') and enumerates what each entry contains (id, type, choices, required flag). The 'contact' scope implicitly separates it from the sibling happyfox_list_ticket_custom_fields, though that sibling is never named 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?

No explicit when-to-use or when-not-to-use guidance and no named alternative. The only guidance is a downstream usage hint ('Use the ids as c-cf-<id>'), which tells the agent how to consume the output rather than when to call the 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 that results carry tagged email domains, which is genuinely useful payload context, but says nothing about pagination, result size, or ordering for a list endpoint that could return many groups.

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

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

Two short sentences, front-loaded with the purpose before the API path. The trailing 'HappyFox: GET /api/1.1/json/contact_groups/.' is implementation trivia of marginal value to an agent, but it costs little and does not obscure the main point.

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

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

For a parameterless, read-only list tool with no output schema, the description covers what the tool returns (groups plus their tagged email domains) well enough to invoke correctly. Only pagination/volume expectations are 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly implies no filtering inputs are required.

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 (contact groups), and usefully clarifies that these are 'typically customer companies' with 'tagged email domains' attached. It does not explicitly contrast with the sibling happyfox_get_contact_group, so the list-vs-single distinction is left implicit.

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: list all contact groups when no specific group is targeted. There is no explicit when-to-use/when-not statement and no mention of the sibling happyfox_get_contact_group for retrieving a single group, so the agent must infer the routing.

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

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

readOnlyHint=true already establishes the read-only safety profile. The description adds real behavioral context beyond annotations: paginated retrieval, the searchable field set, the digit-only phone format, and the underlying endpoint (GET /api/1.1/json/users/).

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

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

Front-loaded with the action and resource, then search syntax, then endpoint. Two compact sentences with no filler. Slightly dense but every clause adds usable 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 3-param list/search tool with annotations present and no output schema, the description covers search semantics, pagination, and the backing endpoint. It stops short of describing return shape or pagination totals, but that is a minor gap given coverage elsewhere.

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 baseline is 3. The description goes further by enumerating the valid `q` fields (name, email, phone, updated_since, created_since), the digit-only phone constraint, space-separated AND semantics, and an example — none of which the schema's 'field:value pairs' description provides.

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

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

The description states a specific verb pair (list/search) and resource (contacts, clarified as customers), plus pagination. It's clear what the tool does, though it does not explicitly name a sibling (e.g. get_contact) to differentiate the single-record vs list case.

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: list paginated or search by field. But there is no explicit when-to-use narrative contrasting it with happyfox_get_contact or happyfox_list_contact_groups, so the agent must infer the selection context.

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

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

readOnlyHint=true already tells the agent this is a safe read with no side effects. The description usefully adds the default (external) and the underlying endpoint paths, but says nothing about pagination, result volume, or auth context for what is framed as an 'export'.

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 default scope front-loaded before the alternative. The raw HappyFox endpoint URLs are marginally useful for debugging but are the only borderline 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 read-only, zero-required-parameter lister whose safety profile is carried by annotations and whose only parameter is fully documented in the schema, the description covers what an agent needs. The one omission is any hint about result volume or paging for an 'export' operation.

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 boolean parameter is already documented there, so the baseline is 3. The description's external/internal wording mirrors the schema rather than adding format or paging semantics beyond it.

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 (export the knowledge base articles) plus the default scope (external/customer-facing) and the optional mode (internal/agent-only). No sibling tool touches the knowledge base, so an agent can route here unambiguously.

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 effectively partitions usage: use it as-is for customer-facing articles, set internal=true for agent-only articles. It does not name exclusions or alternative tools, but with a single boolean mode switch the selection rule is fully stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the underlying endpoint (GET /api/1.1/json/priorities/) and the downstream purpose of the ids, but says nothing about ordering, pagination, or whether the list is static or account-specific.

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

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

Two compact sentences, front-loaded with the action and resource, followed by the value of the ids. The trailing API endpoint reference is mildly redundant but earns its place as a debugging anchor.

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

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

With no output schema, the description carries the burden of describing what comes back. It hints at 'with ids' but does not say whether names/labels are also returned or how the priorities are ordered, which leaves a small gap for an agent assembling a priority value.

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

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

The tool takes zero parameters, so the baseline is 4 — there is nothing for the description to clarify beyond confirming the call needs no arguments.

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 ticket priorities') and adds why the returned ids matter — they are the values used to set a ticket's priority. It does not explicitly distinguish itself from sibling list tools like happyfox_list_statuses or happyfox_list_categories, 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?

Usage is implied rather than stated: by noting the ids are used to set a ticket's priority, the agent can infer this should be called before creating or updating a ticket. There is no explicit when-to-use, when-not-to-use, or named alternative.

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 concrete detail by naming the returned fields and the backing HTTP endpoint (GET /api/1.1/json/reports/), but says nothing about pagination, result limits, or whether all saved reports are returned.

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 no filler; the purpose and returned fields are front-loaded and the endpoint reference is a compact trailing detail. Nothing could be removed without losing information.

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

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

With no parameters, no output schema, and a read-only annotation, the description is nearly complete, and it helpfully enumerates the three returned fields in place of a missing output schema. Only the lack of pagination/scope information (e.g. whether all saved reports are returned) keeps it from being fully complete.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The field list in the description describes the response payload, not inputs, which is a bonus rather than a parameter specification.

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 (saved reports) and even names the returned fields (id, name, description), so the agent knows exactly what comes back. It does not, however, differentiate itself from the closely named siblings happyfox_get_report_summary and happyfox_get_report_tabular_data, which an agent could easily confuse with this 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?

There is no when-to-use statement, no exclusion, and no pointer to the alternative report tools. The agent must infer from the name alone that this is the enumeration step that precedes get_report_summary/get_report_tabular_data.

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 usefully adds the returned fields (ids, roles, categories, active flag) and the underlying REST endpoint. It omits pagination or list-size behavior, keeping it below a 5.

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

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

A single tight sentence front-loads the verb, resource, and returned fields, with the API path appended as a compact mapping hint. 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 zero-param read tool with annotations and no output schema, the description carries the return-value burden well by enumerating the key fields. Nothing an agent needs to call it 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?

The tool takes zero parameters, so the baseline is 4; the description does not need to explain inputs and correctly focuses on output semantics instead.

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

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

Specific verb (list) plus resource (agents/staff), and it resolves the naming ambiguity by equating 'agents' with 'staff'. It clearly distinguishes itself from the many other list_* siblings by naming the entity returned.

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 gives a clear reason to call it: the returned `staff` id is 'what every reply/note needs, and assignee ids,' linking it to happyfox_add_staff_reply and happyfox_add_private_note. No explicit when-not or alternative is stated, 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 goes beyond the annotation by disclosing the shape of the returned data (ids plus behaviour values pending/completed) and the underlying endpoint, which matters because there is no output schema. It still omits auth/pagination/rate-limit details.

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

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

A single compact sentence, front-loaded with the verb and resource, with the payload description and endpoint appended. The endpoint reference is mildly redundant but useful for a bare list call; 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 zero-parameter read-only lister with no output schema, the description supplies the essential missing piece — what the response contains — so an agent can call it and interpret the result. Auth behaviour and pagination are unstated but minor for a small static status list.

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?

This tool takes zero parameters, so per the rubric the baseline is 4. The description adds nothing about inputs because there are none to describe, and the empty schema is fully consistent with the narrative.

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 ('List ticket statuses') and adds what the result contains (ids and behaviour, pending/completed), which distinguishes it from sibling listers like happyfox_list_priorities or happyfox_list_categories by resource name. It stops short of explicitly contrasting itself with a specific sibling, so it sits just below the top band.

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

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

'ids used to change a ticket's status' implies the usage context (fetch ids, then use them in a status-change call), but the description never states when to reach for this tool versus alternatives or any prerequisites. Usage is implied rather than instructed.

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 adds valuable behavioral context beyond that: the returned fields (id, type, choices with choice ids, required flags, categories) and the id format t-cf-<id>. It does not cover pagination or auth, but for a read-only list tool with annotation coverage, this is solid added 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?

The description front-loads the purpose and returned fields in the first clause, then adds a usage note and the underlying API endpoint. It is compact with no filler, though the endpoint line is developer-oriented and not essential for agent selection.

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, so the description must carry the return-value burden; it lists the main returned fields and the id format. It omits pagination or full response shape details, but for a simple, parameterless list tool it is sufficiently 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?

There are no input parameters, so the schema is empty and adds no parameter detail. Per the rubric, zero parameters yields a baseline of 4, and the description appropriately does not invent 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 ('List') and resource ('ticket custom fields'), and enumerates the returned attributes (id, type, choices with choice ids, required flags, categories). It does not explicitly differentiate from sibling tools like happyfox_list_contact_custom_fields or happyfox_update_ticket_custom_fields, so it is clear but lacks sibling routing.

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 guidance on when to use this tool versus alternatives, and no prerequisites or exclusions. The note 'Use the ids as t-cf-<id>' is about consuming the output, not about selecting 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered; the description adds real behavioral detail on top: activity-ordered results, pagination via page_info + data, and that minify_response collapses output to ticket ids only. It omits auth/permission needs and rate limits, which keeps 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?

Front-loaded with purpose, then pagination behavior, then the dense example block — every sentence carries information an agent needs to build a query. The long inline example list is justified by the deferred schema, though it is heavy for a single paragraph and would read better as a list.

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 steps in with a return-shape hint (page_info + data) and the minify_response id-only mode, and it documents all eight parameters including defaults for status and page size. Missing only edge context such as maximum page depth or how total counts are surfaced.

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 schema's `q` entry explicitly defers to the description ('see description') and the description carries that load with real search syntax semantics — quoted OR sets, date formats, tag/contact/unresponded/breached/duedate operators, custom-field syntax. Other parameters gain little beyond the schema, so it is above baseline rather than maximal.

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') plus scope and ordering ('newest activity first, with optional filters'). It is clearly distinguishable from the single-ticket sibling happyfox_get_ticket and from write tools like happyfox_add_staff_reply, but it never names a sibling or states the list-vs-get boundary 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?

Gives concrete guidance for the filter parameter with a dozen worked examples and the composition rule ('Separate several filters with a space'), and flags filters as optional so unfiltered listing is viable. It stops short of any when-not or alternative-tool routing (e.g. 'use get_ticket when you already have an id').

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?

destructiveHint=true already tells the agent this mutates existing data, so the bar is lower. The description adds the useful routing note about phone numbers, but says nothing about whether omitted fields are left intact or cleared, nor about permissions or error behavior for an update that overwrites contact data.

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

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

Two front-loaded sentences with no filler, and the field scope leads before the exception. The trailing API endpoint reference ('POST /api/1.1/json/user/<id>/') is slightly more implementation detail than most agents need.

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 mutation tool with a nested custom_fields object and no output schema, the description covers what is editable, the key format for custom fields, and the phone-number carve-out. It leaves partial-vs-full update semantics unstated, which is a meaningful gap for an overwrite operation.

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 'c-cf-<id>' key format and value typing rules. The description restates the custom-field key convention rather than adding new meaning, which lands at the baseline 3.

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 ('Edit') plus resource ('an existing contact') and an explicit field scope (name, email, custom fields) that separates it from the create path. It also preempts confusion with the sibling happyfox_create_contact by stating where phone-number edits belong.

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 routing guidance: phone numbers are edited via happyfox_create_contact with the phone id, which is effectively a 'when not to use this tool' rule. It does not state broader preconditions (e.g. that the contact must exist, permissions needed), so it stops short of full when/when-not coverage.

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

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

Annotations supply destructiveHint=true, so the mutation risk is declared, but the description adds no behavioral context despite that — notably whether unspecified custom fields are preserved or cleared, whether values are validated against field type definitions, or what comes back. For a destructive write the merge-vs-replace semantics are the single most important undisclosed trait.

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 key format lead, and the raw endpoint follows as supplementary detail. No filler or repetition of schema content.

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

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

With no output schema and only a destructiveHint annotation, the description should cover the gaps that remain — replacement semantics, error cases for invalid field ids, and whether staff must have permissions. It covers the id-sourcing gap well but leaves these behavioral gaps for a nested-object mutation tool.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds value beyond it by naming the id source tool for the t-cf-<id> keys, which the schema's regex pattern alone does not reveal. It still doesn't restate per-type value formats (already in the schema), so it stops short of a 5.

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

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

The description states a specific verb and resource ('Set ticket custom-field values') and pins the key format ('t-cf-<id>'), which cleanly separates this tool from siblings like happyfox_update_ticket_tags or happyfox_create_ticket. An agent can identify the operation 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?

It gives one useful prerequisite pointer ('ids from happyfox_list_ticket_custom_fields'), which tells the agent where to source keys, but there is no explicit when-to-use versus when-not guidance and no mention of the ticket needing to exist or which staff role may perform the change. 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 only supply destructiveHint=true, so the description must carry the rest. It usefully clarifies that other ticket fields are left untouched, but says nothing about permission/auth requirements, whether removing a nonexistent tag errors, or whether repeated adds are idempotent.

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 actionable scope statement front-loaded. The trailing API endpoint reference is marginally redundant for an agent choosing a tool, keeping it just short of a 5.

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

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

With no output schema, an agent gets no signal about what the response contains or how tag operations report partial failure. For a mutation with only destructiveHint coverage, the description is adequate but leaves error and result behavior unspecified.

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

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

Schema description coverage is 100%, including the important note that ticket_number is the numeric id, not the prefixed display id. The description itself adds no parameter-level meaning beyond that, which is exactly the baseline-3 case when structured fields do 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 precise verb+resource ('add and/or remove tags on a ticket') and immediately bounds the scope with 'without touching anything else.' No sibling tool competes for tag mutation, so there is no ambiguity about which tool handles this.

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 'without touching anything else' implies this is a partial update rather than a full ticket edit, which is a mild routing hint against siblings like happyfox_update_ticket_custom_fields. However, it never states when to prefer this tool, whether add/remove can be combined, or any prerequisites such as needing the ticket to exist.

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