happyfox

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

Annotations supply only destructiveHint=true; the description adds real behavioral context by disclosing the note is internal-only (never visible to the contact) and that the call can also alert agents and rewrite status, priority, assignee, due date and tags. That mutation scope corroborates the destructive hint, though reversibility and alert semantics are not spelled out.

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: purpose and the critical internal-only distinction come first, side effects second, endpoint last. 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 12-parameter, nested-object mutation tool with no output schema, the description covers purpose, the internal-only nature and the full set of side effects. It omits return behavior and any note on compulsory custom fields on close (left to the schema), leaving a minor gap.

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

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

Schema description coverage is 100% across 12 parameters, so the schema already documents html/plaintext, alert codes, ids, due-date formats and custom_fields. The description only recaps that alert/status/priority/assignee/due_date/tags can be set and adds no syntax or value beyond the schema, which is the expected baseline here.

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

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

Specific verb+resource (add an internal/private note to a ticket) with the key qualifier "never sent to the contact," which immediately separates it from the customer-facing happyfox_add_staff_reply. It also enumerates the secondary mutations (status, priority, assignee, due date, tags) so an agent knows the call does more than append text.

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?

"Internal note (never sent to the contact)" gives clear selection context against the reply sibling, but the alternative is not named and there are no explicit exclusions or prerequisites. This is clear context without routing language.

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

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

Beyond the lone destructiveHint, the description discloses the customer-email side effect and its default, the property-only mode when message is omitted, the compulsory-custom-fields prerequisite for completion statuses, and the underlying endpoint. No return format is given, but that is a minor gap for a ticket-mutation call.

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

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

Four compact sentences, front-loaded with the tool's two capabilities before the email caveat. The trailing endpoint line is slightly redundant but cheap and useful for debugging.

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 tool with a nested custom_fields object and no output schema, the description covers the behaviors an agent must know before calling: email gating, property-only mode, and completion-field requirements. Response shape is the only substantive 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 coverage is 100%, so the baseline is 3, but the description adds interpretive value: it clarifies that reply and property changes are independent, and that update_customer gates outbound email. It stops short of explaining the cc/bcc or time_spent interactions 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?

States a specific verb and resource ('add an agent reply to a ticket') and extends it with the dual capability of updating status, priority, assignee, due date or tags. The email-gating sentence implicitly separates it from a private-note tool, so an agent can route between the two 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?

Gives clear operating conditions: the contact is emailed only when update_customer is true, and with no message the call is a pure property update. It does not explicitly name happyfox_add_private_note as the alternative when no customer-visible reply is wanted, so one inference step remains.

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 supplies the crucial missing detail of WHAT is destroyed ('any contact custom field NOT passed is reset') and the create-or-edit keying on email. This is meaningful context beyond the annotation. It stops short of describing return values or auth/permission requirements, so not a full 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 dense sentences, front-loaded with the action and the critical reset warning. Every clause earns its place; nothing is repeated from the schema or annotations.

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 no output schema, the description covers the essential risk (custom fields reset), the alternative tool for editing, and the create-or-edit keying. Combined with rich schema coverage, an agent has everything needed to call it 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% and the per-field descriptions (phones, custom_fields, enum meanings) are already thorough, so the schema carries the parameter burden. The description adds no per-parameter syntax or format beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Create a contact') and immediately distinguishes itself from the sibling happyfox_update_contact by naming it. It also clarifies the surprising create-or-edit semantics up front, so an agent can tell exactly what this tool does versus its alternatives.

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 routes the agent: use this to create, and 'use happyfox_update_contact to edit an existing contact.' It also flags the edge case where an existing email triggers an update, which is precisely when an agent might otherwise pick the wrong 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?

With annotations providing only destructiveHint=true, the description adds a genuine behavioral disclosure: the contact is auto-created if the email is new, which is a side effect the agent must anticipate. It does not cover permissions, rate limits, or what the ticket write actually returns, so it is good but not rich.

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

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

Two tight sentences plus an endpoint reference, with the operation and its key prerequisites front-loaded. The HappyFox POST path is arguably 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?

For a mutation tool with no output schema but full schema coverage, the description covers the core operation and the notable contact-creation side effect. Return values and auth expectations remain unstated, but an agent has enough to call it 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 all 15 parameters are already documented (including the public-category constraint and the text/html requirement the description echoes). The description adds no syntax or format detail beyond what the schema carries; 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 ('Open a new ticket') on behalf of a contact, and distinguishes itself from creation siblings (create_contact) by naming the side effect of creating a contact when the email is new. 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?

The description lists prerequisites (public category, subject, text/html message), which is useful context, but it never states when to pick this tool over alternatives or any when-not conditions. Usage is implied 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 safety is covered; the description adds value by disclosing the returned payload (phones, contact groups, ticket counts, custom fields) and the underlying API endpoint. It stops short of noting auth requirements, rate limits, or error behavior for an unknown id/email.

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 the API path; the lookup behaviour and returned fields are front-loaded and nothing is wasted.

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

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

With no output schema, the enumeration of returned fields usefully compensates, and read-only behaviour is covered by annotations. A brief note on ambiguous or missing lookup keys would make it fully complete.

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

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

Schema coverage is 100% and the single 'contact' parameter is already documented with its id/email formats. The description restates the same id-or-email duality without adding syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('a contact') plus the two lookup keys (id or email) and enumerates what the response contains. An agent can distinguish this from happyfox_list_contacts or happyfox_get_contact_group 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?

Implicit usage is conveyed by 'by id or by email address', and the sibling list makes the single-vs-list distinction inferable, but the description never explicitly says when to prefer this over happyfox_list_contacts or happyfox_update_contact, nor does it state any prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds only the raw REST endpoint path and the note that member contacts are included; it discloses nothing further about pagination, result size, or error 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 short sentences, front-loaded with the purpose. The endpoint path is marginally useful but borders on filler; overall it is tightly sized.

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 tool with readOnlyHint annotations and no output schema, the definition is sufficient; it even hints at the payload ('its member contacts'). No return-format detail is required given the simplicity.

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

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

Schema coverage is 100% with a single well-described integer id, so the schema carries the parameter meaning. The description only mirrors the id via the endpoint template, adding nothing 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 ('Fetch') and resource ('a contact group and its member contacts'), which distinguishes it from the plural 'list_contact_groups' sibling by implication. It is clear but does not explicitly name any sibling or contrast condition.

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 singular resource and required id — clearly the single-item lookup versus list_contact_groups — but no when-to-use, prerequisites, or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the shape of the response (ticket, completed, assigned, pending, unassigned counts), which is genuinely useful since no output schema exists, but it says nothing about permissions, rate limits, or empty/error states.

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 return content. The trailing REST endpoint reference is mildly extraneous for an agent but compact and harmless.

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

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

With no output schema, the description correctly carries the return-value burden by listing the count categories. For a simple single-parameter read tool this is nearly complete; only the absence of any error/empty-state note 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?

There is a single parameter at 100% schema description coverage, and the schema already explains that report_id comes from happyfox_list_reports. The description ('a saved report') only loosely reinforces this, so the baseline 3 applies.

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

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

The description gives a clear verb+resource ('Summary counts for a saved report') and even enumerates the specific count categories returned, so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the sibling happyfox_get_report_tabular_data, so an agent cannot route between the two 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 when-to-use statement and no mention of the obvious alternative (happyfox_get_report_tabular_data) or when to prefer tabular data over aggregates. The only routing hint, that a report id comes from happyfox_list_reports, lives in the schema rather than the description.

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 cover the read-only safety profile, so the description's job is to add behavior — and it does: it discloses the one-row-per-ticket granularity, the paginated nature, the row fields, and the underlying endpoint. It stops short of stating default page size or result limits, but adds real context beyond the annotation.

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

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

A single compact sentence with the resource and granularity front-loaded and the endpoint appended; no filler, no redundancy.

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

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

With no output schema, the description carries the burden of describing the return value, and it does by listing the row columns and noting pagination. It is nearly complete, lacking only pagination defaults/limit context that would fully close the gap.

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

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

Schema description coverage is 100%, so page, size, and report_id are fully documented in the schema. The description mentions pagination and identifies the row fields but adds no syntax or filtering semantics beyond what the schema already 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+resource: the tabular view of a saved report, one row per ticket, with the returned fields listed. It implicitly contrasts with happyfox_get_report_summary (tabular vs. summary), but never names that sibling, so differentiation is inferred rather than stated.

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

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

The description offers no when-to-use guidance and does not name an alternative or a precondition (e.g. use get_report_summary for aggregates, or that the report must exist). The only hint is inside the schema's report_id text, not the description.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context beyond that: it returns every update including private notes and property changes, and warns that attachment links expire in 5 minutes. It lacks permission or rate-limit details but adds real 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?

A single front-loaded sentence enumerates the return contents, followed by a compact API endpoint reference. There is no filler; every element informs the agent about scope or return data.

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 bears the burden of describing return values and does so well by enumerating fields, conversation updates, and attachment expiry. It omits some structural details such as response nesting or update ordering, keeping it short of fully complete.

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

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

Schema description coverage is 100%, so both ticket_number and show_cf_changes are fully documented in the schema. The description does not add syntax or meaning beyond the schema, making the baseline score of 3 appropriate.

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

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

States a specific verb ('Fetch') and resource ('ticket') and defines the scope as a single ticket with its full conversation. The enumerated return fields further distinguish it from sibling list tools like happyfox_list_tickets by emphasizing one ticket's complete history.

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?

Implied usage is clear: retrieve a single ticket's full details. However, it does not explicitly say when to use this versus happyfox_list_tickets or other sibling tools, leaving routing to inference.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds the underlying endpoint (GET /api/1.1/json/categories/) and the fact that ids are the payload, but does not cover pagination, caching, or whether inactive queues are included — useful but not rich beyond the annotation.

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

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

One compact sentence delivering purpose, alias, return content, and downstream need, plus a short endpoint reference. No filler and 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?

With no output schema, the description correctly summarizes the return value ('categories with their ids'). It is sufficient for a zero-parameter read tool, though naming the fields returned (e.g., name, id, visibility) would make it fully self-contained.

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 argument semantics to explain; the baseline for a parameterless tool applies. The description correctly implies the call is unconditional.

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'), disambiguates with the synonym '(queues)', and states what is returned ('their ids'). An agent can distinguish it from happyfox_list_priorities/statuses/contacts without opening any schema.

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

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

Gives clear downstream context: the ids are 'needed to create a ticket or filter tickets' (i.e., call this before happyfox_create_ticket or happyfox_list_tickets). It does not explicitly name those sibling tools or state exclusions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context beyond that: the GET endpoint, the returned fields (id, type, choices, required flag), and how to use the returned IDs. It lacks auth/rate-limit details, but for a simple read this is solid.

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 plus an endpoint, with the core purpose front-loaded. Every element (purpose, returned fields, ID usage, endpoint) adds value and there is 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-parameter, read-only list tool with no output schema, the description provides everything needed: purpose, returned fields, ID usage, and the underlying API call. Complete and appropriately scoped.

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

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

The tool has zero input parameters, which yields a baseline of 4. The description appropriately does not discuss input parameters and instead explains the output fields and ID formatting.

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 specific verb 'List' and resource 'contact custom fields', and distinguishes from the sibling happyfox_list_ticket_custom_fields by scoping to contact fields. Also enumerates returned fields, so the agent knows exactly what the tool provides.

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

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

No when-to-use guidance or alternatives are given. The only usage note is about formatting returned IDs as c-cf-<id>, which is output usage rather than tool-selection 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 establishes this as a safe, non-mutating read, so the description's main added value is the note that results include tagged email domains and the underlying endpoint. It does not mention pagination, result limits, or ordering, which are the remaining behavioral gaps for a list operation.

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

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

Two tight sentences with the resource and its meaning front-loaded. The trailing API endpoint reference is mildly redundant but not distracting.

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 tool with annotations covering safety and no output schema, the description gives adequate return-content context (email domains) and domain context (customer companies). It falls short on pagination/volume expectations, which an agent listing a potentially large collection would benefit from knowing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading parameter language is present.

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 the parenthetical 'typically customer companies' plus 'with their tagged email domains' clarifies what the resource actually is. It is distinguishable from the singular happyfox_get_contact_group, though it does not explicitly name that sibling.

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

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

No when-to-use guidance, no exclusions, and no routing to alternatives such as happyfox_get_contact_group for a single group or happyfox_list_contacts for contacts. Usage is only implied by the verb 'List'.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower, and the description adds real behavioral detail beyond it: pagination, the searchable fields, the phone 'digits only, no +' constraint, and the 'space-separated, all must match' matching semantics. It does not disclose the response shape, but the search behavior 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?

The description is dense but front-loaded, leading with what the tool does before the search-field detail and the underlying API endpoint. Every clause carries information; the only slightly extraneous element is the trailing endpoint reference.

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

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

For a list/search tool with no output schema, the description supplies the two things an agent most needs — pagination behavior and the syntax/semantics of the search query, including a worked example. Combined with readOnlyHint annotations, an agent has enough to call it 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 coverage is 100%, so the baseline would be 3, but the description enriches `q` well beyond the schema by enumerating the searchable fields (name, email, phone, updated_since, created_since), giving a concrete example, and stating the AND-matching rule and phone format. This adds meaning the schema's generic 'field:value pairs' string does not convey.

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 opens with a specific verb+resource ('List contacts (customers), paginated, or search them'), making the list/search batch nature clear and implicitly distinct from the singular get_contact sibling. It stops short of explicitly naming that sibling, so the differentiation is inherent rather than stated.

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

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

Usage is implied: the tool lists or searches, and the field list tells the agent what can be searched. However, there is no explicit when-to-use guidance — e.g., when to reach for this versus happyfox_get_contact for a single record, or how it relates to list_contact_groups.

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 a genuinely behavioral fact beyond the annotations: the default result set is external (customer-facing) articles, not internal ones. That default matters for interpreting the output. It stops short of covering pagination, size limits, or return shape.

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 primary behavior (export, default = external) front-loaded. The trailing HappyFox API endpoint paths are arguably extra detail, but they identify the underlying resource and are 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?

For a read-only export with a single fully-documented boolean and no output schema, the description gives an agent everything needed to invoke it correctly. It does not mention pagination or result volume, a minor gap for a list/export endpoint.

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

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

Schema coverage is 100% and the sole parameter is already described as 'true = internal articles; false/omitted = external'. The description echoes this same true/false semantics plus the default, adding marginal value. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (export) and resource (knowledge-base articles), and disambiguates the two modes it returns: external/customer-facing by default vs internal/agent-only. There are no KB-related siblings to confuse it with, so sibling differentiation is moot, but the modal distinction is clearly drawn.

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 tells the agent the default (external articles) and that internal is opt-in, which is useful. However, it never states when to use this tool versus alternatives, nor any prerequisites (e.g. KB module enabled, permissions), leaving usage largely implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying GET endpoint, which is mildly useful context but does not add behavioral detail such as pagination or response shape.

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 that front-loads the resource and its purpose. The trailing API endpoint mention is somewhat redundant for an agent deciding whether to call the tool, but costs little.

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

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

For a simple read-only list operation with no parameters and no output schema, the description gives enough to invoke it correctly. Return-value detail is not required since the tool is a trivial enumeration.

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 and calls an endpoint with no query args, so the baseline for no-param tools applies. There is nothing further the description could clarify about 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 priorities with ids') and explains what the ids are for, which separates it from the sibling list_* tools by resource. It stops short of explicitly contrasting with those siblings, so it lands just below the top tier.

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 'ids used to set a ticket's priority' implies the use case (fetch ids before setting priority) but there is no explicit when-to-use, prerequisite, or alternative guidance. 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 readOnlyHint annotation already establishes this is a safe read, and the description confirms it by naming the HTTP method (GET) and endpoint. It adds the returned field list, but says nothing about pagination, result limits, or whether unshared/archived reports are included.

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 zero filler; the purpose and returned fields are front-loaded before the technical endpoint detail. Every sentence earns its place.

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

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

With no output schema, the description usefully covers the return shape, and with no parameters and a read-only annotation there is little else an agent needs. Behavior around large result sets or filtering is not addressed, but the omission is minor.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description goes slightly further by documenting the response fields (id, name, description) even though there are no inputs to describe.

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

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

The description states a specific verb (List) and resource (saved reports from the Reports module) and even specifies the returned fields (id, name, description). It implicitly differentiates from siblings like get_report_summary and get_report_tabular_data, though it never names 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 explicit when-to-use guidance. With siblings get_report_summary and get_report_tabular_data in the same module, the agent must infer that this tool is the discovery step, but the description never states that or when to prefer each 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?

readOnlyHint=true already establishes this as a safe read, so the description's added value is the field inventory the call returns and the underlying endpoint (GET /api/1.1/json/staff/). Since no output schema exists, surfacing the returned attributes is genuinely useful; pagination or rate-limit behavior is not addressed, but for a zero-parameter read this is minor.

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

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

A single dense sentence front-loads the resource and its returned fields before the 'why you need it' clause, with the endpoint appended. No filler or restatement of the title.

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

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

For a zero-param, read-only listing with no output schema, the description carries exactly the missing pieces: what attributes come back and why the ids matter to sibling tools. Nothing an agent needs in order to call it correctly 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?

The tool takes no parameters, so the baseline is 4 and there is nothing to disambiguate. The description adds only that the call is unfiltered in the sense that it returns the full staff roster, which is consistent with the empty 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?

Specific verb+resource ('List agents (staff)') with an immediate terminology bridge to the `staff` nomenclature used elsewhere in the API. It also names the exact fields returned (ids, roles, categories, active flag), so the agent knows precisely what this yields versus generic directory-style siblings like 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?

It states the concrete downstream need this tool serves: obtaining the `staff` id required by every reply/note, plus assignee ids for ticket work. That is strong contextual guidance for when to reach for it, though it names no explicit alternative or 'when not to use' condition.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantive knowledge beyond them: the payload contains status ids plus a pending/completed behaviour field, and it notes the backing endpoint (GET /api/1.1/json/statuses/). It omits ordering, pagination, or whether the list is 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?

A single front-loaded sentence: purpose and payload first, then the exploitation hint, then the endpoint. Every clause earns its place and nothing is repeated from structured fields.

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 readOnly annotation, this is nearly complete — the return shape (ids + pending/completed behaviour) is described even though there is no output schema. A note that all statuses are returned unconditionally would close the last gap.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly spends no words on 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 and resource ('List ticket statuses') and adds the returned content ('ids and behaviour (pending / completed)'). The resource noun alone distinguishes it from sibling enumerators like list_priorities, list_categories and list_staff.

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

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

Gives clear context for calling it: the ids are used to change a ticket's status, implying you fetch these before an update. It stops short of naming an explicit alternative or a when-not condition, but the trigger context is unambiguous.

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. Beyond that, the description adds real behavioral value by disclosing the returned attributes (id, type, choices with choice ids, required flags, categories) and the id-prefix convention for downstream use — important given there is no output schema. It omits pagination and rate-limit behavior, keeping it short of a 5.

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

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

Two sentences, front-loaded with the resource and the concrete return fields. The trailing 'HappyFox: GET /api/1.1/json/ticket_custom_fields/.' is mildly redundant with the tool name but plausibly useful for tracing the endpoint, so it is not wasteful enough to penalize further.

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 and no output schema, the description usefully stands in for the missing return contract by enumerating the fields returned and the id convention. It does not address result size, pagination, or ordering, which is the only real gap for a list endpoint.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter text is needed or expected here.

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 custom fields') and immediately distinguishes itself from the sibling happyfox_list_contact_custom_fields by scoping to tickets. An agent can tell exactly what this returns without opening anything else.

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: the description tells the agent how to consume the ids ('Use the ids as t-cf-<id>'), which is a downstream use cue, but never says when to call this versus happyfox_update_ticket_custom_fields or why one would list fields. No prerequisites or exclusions are given.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds value beyond it: the default ordering (newest activity first) and the pagination shape (page_info + data). It does not describe rate limits or the exact response envelope contents, but for a read-only list tool this is solid disclosure.

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 and ordering, then the filter examples. The long run of query examples is dense but each is a distinct, usable filter token, so the length is largely earned; only the trailing raw endpoint reference (GET /api/1.1/json/tickets/) 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 no output schema, the description steps in to note the pagination envelope (page_info + data) and the minify option exists via schema. For a read-only search tool with fully documented parameters and safety annotations, this is complete enough, though it could note result ordering interaction with `sort`.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema for the most important parameter by supplying nine concrete `q` filter examples (status, priority, assignee, tag, contact, unresponded, breached, duedate, date filters) and the space-separation rule, which the schema only gestures at with 'see description'.

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 the default ordering ('newest activity first') and that it doubles as a search endpoint. An agent can distinguish it from happyfox_get_ticket (single ticket) and happyfox_create_ticket (write) 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?

Makes clear that filters are optional and that search runs through the `q` parameter, giving concrete filter-syntax examples that imply the filtering use case. It stops short of stating when to prefer this over happyfox_get_ticket or other list tools, so no explicit exclusions or alternatives are named.

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

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

Annotations provide destructiveHint=true, so the safety profile is partly covered. The description adds the API endpoint and the phone-number caveat, but does not disclose the critical mutation semantics for a destructive tool: whether omitted fields are cleared or left untouched, and any auth requirements. Useful additions, meaningful gaps remain.

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

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

Three short sentences with the edit scope front-loaded, the phone-number exception second, and the endpoint last. Every sentence carries information and nothing is padded.

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

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

No output schema exists, so return values are not required, and the schema fully covers the 4 parameters including the nested object. The description covers editability and a routing caveat; only the partial-update behavior of a destructive mutation is left 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%, so name, email, contact_id, and the custom_fields key pattern/value types are already documented in the schema. The description echoes the c-cf-<id> key convention without adding syntax or format detail beyond it, 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 (edit) and resource (contact) and enumerates the editable fields (name, email, custom fields). It also distinguishes itself from happyfox_create_contact by routing phone-number edits there, so an agent can separate it from its closest sibling without opening a schema.

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

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

Explicitly tells the agent when to use a different tool: phone numbers must go through happyfox_create_contact with the phone id. That is a genuine alternative-routing rule, but there is no broader guidance (e.g. partial vs full update, prerequisites, or when to prefer get_contact 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, so the safety profile is partially covered, and the description adds the underlying POST endpoint. It still does not explain why the operation is destructive (i.e., whether existing values are overwritten vs merged) or note authorization needs, leaving the key behavioral question unanswered.

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

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

Two compact sentences with the action front-loaded and the id-source dependency immediately following. The raw endpoint sentence is mild boilerplate but conveys the HTTP method, so waste is minimal.

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

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

For a three-parameter destructive mutation with a nested object and no output schema, the schema carries parameter detail but the description omits the merge-vs-replace behavior and any permission requirements. Adequate to invoke, but not fully complete on the semantics an agent should know before writing.

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

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

Schema description coverage is 100% and the schema already documents the t-cf-<id> key pattern, value-type mapping, and the ticket_number semantics. The description only restates the key format and names the id source, adding little beyond structured fields, 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 ('Set ticket custom-field values') and disambiguates from the sibling list tool by pointing to happyfox_list_ticket_custom_fields for ids. An agent can tell what it does and what it is not (e.g., not updating tags or a ticket itself).

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 a useful dependency pointer to happyfox_list_ticket_custom_fields for obtaining custom-field ids, which implies the intended workflow. However, it never states when to use this versus sibling mutators, nor any prerequisites such as required permissions or whether values are replaced.

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 the description usefully narrows the blast radius ('without touching anything else'), which tells the agent that non-tag fields survive. It also exposes the underlying endpoint, but says nothing about auth requirements, behavior when adding a duplicate or removing a nonexistent tag, or error/reversal characteristics. Modest added value on top of the annotation.

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

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

Two sentences, front-loaded with the behavior and followed by 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?

Covers purpose, mutation scope, and endpoint, and the schema fully documents the four parameters. However, for a destructive mutation with no output schema it leaves open what a successful response looks like, whether partial failures (e.g. removing a missing tag) error out, and whether tags are case-sensitive. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and each parameter is documented in the schema (comma-separated add/remove strings, staff_id, the critical 'ticket NUMBER not display id' caveat). The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (add/remove) plus resource (ticket tags) and adds a scoping clause ('without touching anything else') that separates it from sibling mutators like happyfox_update_ticket_custom_fields. 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?

No explicit when-to-use guidance, no prerequisites, and no named alternatives among the many sibling update tools. The 'without touching anything else' phrasing implies narrow targeting, but the agent must infer when to choose this over a broader ticket update.

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