Vision Helpdesk MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true. The description reinforces the write gate ('confirm:true required') and narrows the effect to an internal note, which is useful context. It does not explain why the operation is flagged destructive, nor what the confirm gate is protecting against, so the addition is modest.

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

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

Front-loaded with 'WRITE:' and the confirm requirement, which is correct. The third sentence is a compressed, ambiguous fragment ('ticket / add_note with notetype 1') that costs clarity without earning its place.

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

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

For a 3-parameter mutation with full schema coverage and complete annotations, the description covers the write/confirm gate and the internal (non-client-visible) scope. It omits what the tool returns, whether the note is immediately visible to staff, and any error conditions — acceptable but not complete for a destructive-flagged write.

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 schema already documents note, confirm, and client_id — baseline 3. The phrase 'notetype 1' does add a semantic mapping not present in the schema (internal note = note type 1), but it is unexplained shorthand rather than actionable guidance.

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 internal note to a client record'), which distinguishes it from the sibling vision_add_ticket_note by scope (client vs ticket). The trailing fragment 'ticket / add_note with notetype 1' is cryptic and muddies an otherwise clear statement, keeping it from a 5.

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

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

'WRITE: confirm:true required' gives a precondition, and 'internal note' implies the when-not case (nothing client-visible or emailed). However, it never explicitly names vision_add_ticket_note as the alternative for ticket-scoped notes, leaving the 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is covered; the description adds context annotations do not — the note is internal and never surfaced to the client, and it maps to the ticket/add_note endpoint with notetype 0. It does not say what happens to the ticket (status change, timestamps) after the write, which keeps this 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?

Very short and front-loaded with the write/confirm warning before the purpose, which is the right order. The redundant restatement of the title ('add an internal note to a ticket') and the terse endpoint fragment are minor filler but nothing is verbose.

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

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

For a 3-parameter, no-output-schema write tool, the description covers the mutation gate, the audience of the note, and the underlying operation. Missing only the post-write observable effect, which an agent might want but does not need 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 confirm, ticket_id and note are all documented in the schema; the description only echoes the confirm requirement and adds the notetype 0 detail, which is about the backend call rather than the parameters. Baseline 3 applies when the schema carries the 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 ('add an internal note to a ticket') and disambiguates by effect ('not shown to the client'), which separates it from client-facing reply/note tools. It never names the closest sibling (vision_add_client_note or vision_reply_to_ticket), so the differentiation is left 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 'confirm:true required' prerequisite and the internal-not-client-visible framing imply when this is appropriate instead of reply_to_ticket, but there is no explicit 'use this when X, use reply_to_ticket when Y' statement or statement of exclusions.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is structured. The description adds the genuinely useful detail that a confirm flag gates the write, plus the 'add_live_tag' hint that the change is live/client-visible. However, it never explains what the destructive aspect actually means (whether tags can be removed, whether notifications fire), which the schema's mention of 'email effects' suggests is relevant.

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 front-loading of 'WRITE: confirm:true required' is good practice and puts the most critical constraint first. But the trailing fragment 'ticket / add_live_tag.' is cryptic, unexplained shorthand that consumes space without conveying clear meaning to 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?

For a three-required-parameter write tool with no output schema, the description covers the essential call requirements: it is a write, it needs confirm=true, and the tag is given by title. The one gap is the unexplained 'add_live_tag' token, which a reader cannot interpret with confidence.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema. The description adds only a marginal clarification that the tag is identified by title rather than id, which is a small but real contribution beyond the structured field. Baseline 3 applies since 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?

The description names a specific verb and resource ('add a tag ... to a ticket') and adds the lookup key ('by title'), which distinguishes it from the other tag-related siblings such as vision_list_tickets_by_tag. It is clear what the tool does, though it does not explicitly contrast itself with the note/assignment siblings.

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

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

It states the precondition 'confirm:true required' and flags the operation as a WRITE, which implies when it applies. There is no guidance on when not to use it or which sibling to prefer (e.g., label vs. tag listing tools), leaving selection 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 already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description repeats 'WRITE' and the confirm requirement, which is also encoded in the schema, but adds little context about what removal affects, client-visible/email consequences, or authorization needs.

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 write warning and confirm requirement are front-loaded, and the description is short. However, the fragment 'ticket / update_properties with action staff' is an internal implementation detail that does not help an agent invoke the tool and makes the structure feel fragmented.

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?

The annotation and schema cover the safety profile and all parameters, and the confirm requirement is surfaced. Still, for a destructive mutation tool, the description could say more about side effects of unassignment and when this specialized staff operation is appropriate.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description references action staff and the ticket/staff target, but adds no format or semantic 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 states a specific action and resource: add a staff member as a ticket owner or remove one, with the action staff detail. It is clearly narrower than the generic vision_update_ticket_property sibling, though it does not explicitly name that alternative.

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 prerequisite (confirm:true required) and states the assign/unassign purpose, implying when the tool is used. However, it does not explain when to choose this over vision_update_ticket_property or when to prefer assign versus unassign beyond the enum.

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

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

Goes well beyond the annotations: pins down the default email/autoresponder suppression, explains the client-visible effect of the first post, and spells out the internal-ticket constraint that forbids client recipients and email. These are exactly the client-visible side effects the destructive/openWorld annotations signal but cannot describe.

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

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

Front-loads the write confirmation and default side-effect posture before details, which is the right order for a mutating tool. The trailing fragment 'ticket / open_new_ticket.' is unexplained noise, and the density makes it slightly hard to scan.

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 an 18-parameter, non-idempotent, destructive write with no output schema, the description covers confirmation, defaults, and the internal-ticket edge case well. What is missing is what the call returns (e.g., the new ticket id) and any note on cc/owner behavior, which matter because there is no output schema to fall back on.

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 every parameter already carries its own description; the description's parameter content ('client id or email', defaults for email/autoresponder) largely mirrors the schema. It adds the workflow hint of resolving department/status/priority/type ids first, but nothing about cc, owner_ids, as_client, or visible_to_client beyond what the schema states.

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

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

Opens with a specific verb and resource ('open a new ticket for a client') and immediately scopes the actor ('given by client id or email'). This clearly separates it from siblings like vision_reply_to_ticket or vision_add_ticket_note, which operate on existing tickets.

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

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

Gives a strong precondition ('confirm:true required'), names the companion lookup tools (vision_list_statuses, vision_list_priorities, vision_list_ticket_types) that must be called first, and states the internal-ticket restriction. It does not explicitly say when to prefer vision_reply_to_ticket instead of creating a new ticket, but the framing as 'first post' implies it.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is carried by structured data. The description's only added behavior detail is what the summary contains (notes and ticket counts), which is modest value but real; it says nothing about response shape, aggregation period, or whether counts are lifetime or open-only.

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 fragments with no filler, and the resource-and-contents information is front-loaded. The trailing 'client / get_summary' largely restates the tool name, so it earns little, but the overall size is not wasteful.

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

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

For a single-parameter read-only lookup, the description tells the agent what comes back (notes and ticket counts), which is the main missing piece given there is no output schema. However, it does not say whether counts are scoped (open vs. all tickets), nor how a missing or unknown client_id behaves, so gaps remain.

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

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

Only one parameter, client_id, and schema coverage is 100% with its own description, so the schema fully documents the input. The description adds no format, range, or lookup guidance beyond that, which is the baseline case for a single well-documented parameter.

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 is a noun fragment, 'A client's summary: notes and ticket counts,' with no verb, but it does name the resource and the two data categories returned. That is enough to tell it apart from vision_get_ticket and vision_get_dashboard_counts, though the phrasing is clipped rather than declarative.

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

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

There is no statement of when to use this versus vision_search_clients or vision_get_dashboard_counts, and no prerequisites such as needing a valid client_id. The agent is left to infer usage entirely from the name and the one-line content hint.

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 and destructiveHint=false, so the safety profile is covered. The description adds the useful scope of returned counts (new, open, overdue, assigned), but does not disclose return shape, freshness, or any authorization/rate-limit context.

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 short and front-loads the main purpose. The trailing fragment 'ticket / quick_view.' is somewhat cryptic and slightly reduces polish, but overall there is little waste.

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

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

For a zero-parameter read-only tool with no output schema, the description is only partially complete: it lists example count types but does not specify the exact return fields or dashboard scope. It is adequate to recognize the tool, but not 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 has zero parameters, so parameter semantics are inherently simple and the schema has nothing to document. The description does not need to explain parameters and creates no confusion.

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 identifies a specific resource (staff dashboard ticket counts) and gives example categories, so the basic intent is clear. However, it is phrased as a noun fragment rather than a clear verb+resource statement and does not explicitly distinguish this quick-view count tool from sibling ticket-listing/search tools.

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

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

It implies use for a dashboard quick view, but gives no explicit guidance on when to use this tool versus alternatives such as vision_list_tickets or vision_get_client_summary. There are no exclusions or conditions 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful scope information by disclosing that the result bundles both the ticket fields and the conversation posts. However, it says nothing about behavior when the ticket id is missing/invalid or how large the posts payload might be, and with no output schema the return shape is only partially characterized.

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 core sentence is short and front-loaded with the right information (single ticket, fields, posts). The dangling 'ticket / ticket_details.' fragment is unexplained noise that a reader cannot act on.

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 strong annotations this is close to sufficient — it says what comes back. It stops short of routing the agent away from the list/search siblings and gives no guidance on the common failure mode of an invalid or unknown ticket id.

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 clarifies 'the number, not the reference', so the description is not obligated to explain the parameter. The cryptic 'ticket / ticket_details' tail could be read as hinting at accepted identifiers but is too ambiguous to add reliable meaning.

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 identifies the resource precisely — a single ticket plus its fields and posts — which cleanly separates it from the list/search siblings that return collections. The verb is only implied ('One ticket with...') rather than stated as 'Get/retrieve', and the trailing 'ticket / ticket_details' fragment adds no clarity.

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

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

There is no statement of when to use this versus vision_list_tickets, vision_search_tickets, or vision_get_client_summary, and no prerequisites mentioned. The only implicit guidance is that a ticket_id is required, which the schema already conveys.

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 destructiveHint=false, so the safety profile is covered. The description adds the meaningful mutual-exclusivity constraint, but says nothing about what happens if more than one filter is supplied (error? ignored?) or the fact that the server returns the full list before local truncation.

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

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

One compact sentence with the scope constraint front-loaded. The trailing 'client / get_clients' token is clutter that earns nothing for the 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?

For a simple read-only list tool with full schema coverage and annotations, the essentials are present. Still missing: behavior on conflicting filters, and any hint that results are truncated client-side (the limit description mentions it, but the description does not reinforce it) or how it relates to search_clients.

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 parameter meanings are already documented. The description adds value beyond the schema by stating that client_id, first_name and parent_id are mutually exclusive and that parent_id enumerates a client's contacts — the schema alone would let an agent pass all three.

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 clients (customers)') and adds the distinguishing constraint that at most one filter may be used. It does not differentiate itself from the sibling vision_search_clients, so the boundary between 'list' and 'search' is left unclear.

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 'at most ONE filter' rule with the three allowed filter kinds gives real usage context, but there is no guidance on when to pick this over vision_search_clients (which presumably handles fuzzy/text filters). The trailing 'client / get_clients' is an opaque reference that doesn't help an agent decide.

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 that this is a read-only, non-destructive, open-world operation. The description adds useful context about department scoping and return shape (ids and names), but does not discuss ordering, pagination, 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?

The description is short and front-loads the resource scope, but the trailing fragment 'ticket / get_priority.' is cryptic and does not clearly earn its place for an agent trying to 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 simple one-parameter read tool, the description gives enough to know the required department scope and return fields. However, it omits routing context relative to similar list tools and leaves the odd 'ticket / get_priority.' notation unexplained.

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

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

Schema coverage is 100% and the sole parameter department_id is already documented as 'Department id.' The description adds no additional syntax or semantic detail beyond restating department scoping.

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 clearly identifies the resource as ticket priorities scoped to a department and notes the return fields (ids and names). It is distinguishable from siblings like vision_list_statuses and vision_list_ticket_types by resource, though it lacks an explicit verb.

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

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

There is no guidance on when to use this tool versus alternatives such as vision_list_statuses or vision_list_ticket_types. Usage is only implied by the noun phrase and department scope.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context that statuses are per department and include ids and names, but it does not disclose pagination, ordering, or permission behavior beyond what the annotations provide.

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

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

The description is short and front-loads the key information about what is returned and why it is useful. The trailing 'ticket / get_status.' is slightly cryptic, but overall it remains efficient.

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

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

For a simple read-only list tool with one fully documented parameter and no output schema, the description supplies adequate return-content context: ids and names. It could be more complete by noting ordering or pagination, but the essential information is present.

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 department_id as the required department id. The description's phrase 'of a department' reinforces scope but adds no syntax or format detail beyond the schema.

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

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

The description states the specific resource and scope: ticket statuses of a department, including ids and names. It is clear enough to distinguish from sibling tools like vision_list_priorities or vision_list_ticket_types, though it does not explicitly name those 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?

The phrase 'for filters and status changes' implies when the results are useful, but it does not explicitly say when to use this tool versus similar list tools. No exclusions or alternative-selection guidance are provided.

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 safety (readOnlyHint true, destructiveHint false), so the description adds the non-obvious behavioral facts: the single-filter constraint and the default visibility scope ('tickets the API user can see') when no filter is given. It says nothing about pagination or result shape, but limit/offset are documented in the schema.

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

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

Four short sentences, front-loaded with the operation and its key constraint; no filler. Minor redundancy: the folder values are repeated verbatim from the schema enum, and the trailing 'ticket / get_tickets' fragment is cryptic.

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 7-parameter, zero-required list tool with full schema coverage and no output schema, the description supplies the two things the schema cannot: the mutual-exclusion rule and the unfiltered default. What an agent gets back and how to page through it is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already explains limit, offset, include_count and each id parameter; that sets the baseline at 3. The description does add genuine cross-parameter meaning by declaring only one of ticket_id/status_id/department_id/folder may be used, which a per-property schema cannot express.

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 tickets') plus the module of filtering allowed, and ends with the API resource hint 'ticket / get_tickets'. It is clear against generic siblings like vision_create_ticket or vision_get_ticket, but it never explicitly distinguishes itself from vision_list_tickets_by_tag, vision_list_tickets_by_label, or vision_search_tickets.

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

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

Gives a real usage rule that cannot be read off the schema: at most ONE filter may be supplied, and with no filter it lists everything the API user can see. It also routes the agent to vision_list_statuses for status ids. It stops short of naming when to prefer vision_search_tickets or the tag/label listers instead.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no pagination behavior, no note on whether all matching tickets are returned, no ordering, and no mention of the open-world lookup implied by label resolution.

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?

It is short, so there is no padding, but it is not a well-formed front-loaded sentence. The fragment structure and dangling keyword tail make it less useful than one clean sentence would be.

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 listing tool with no output schema, the description should say what is returned and how results are bounded. It says none of that, and it also fails to separate this tool from its near-identical tag-based sibling, leaving real ambiguity for an agent choosing among 18 tools.

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

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

Schema description coverage is 100% for the single label_id parameter and the description only restates that the filter is by label id. With one fully documented parameter and no enums, the baseline of 3 applies since nothing extra is contributed.

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 phrase "Tickets that carry a label, by label id" identifies the resource (tickets) and the filter (label id), but it is a fragment rather than a clear verb+resource statement. It does not distinguish this tool from the sibling vision_list_tickets_by_tag, which has an almost identical shape.

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

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

There is no guidance on when to use this versus vision_list_tickets or vision_list_tickets_by_tag. The trailing "ticket / search_label_tickets." reads like leftover keywords rather than an instruction, so the agent must infer the selection criteria.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no indication of what is returned (ticket summaries vs. full tickets), whether results are paginated or capped, or what happens when the tag id does not exist.

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 length is appropriate for a one-parameter read tool, and the resource is front-loaded. However, the second fragment "ticket / tag_search" is unexplained jargon that consumes space without earning it, and the whole description is arguably too terse rather than too long.

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 one required parameter, full schema coverage, and annotations covering the safety profile, the description is minimally sufficient to invoke the tool. It is incomplete in that it never clarifies the tag-vs-label distinction from its closest sibling, which is the most likely source of a wrong tool choice.

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

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

Schema description coverage is 100% and the single parameter tag_id is fully documented in the schema, so the baseline is 3. The description's "by tag id" merely restates the schema and adds no format, range, or lookup guidance 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?

The phrase "Tickets that carry a tag, by tag id" does identify the resource (tickets) and the filter (tag id), but it is a noun phrase with no verb and reads as a restatement of the tool name. Critically, it never distinguishes this tool from the very similar sibling vision_list_tickets_by_label, so an agent cannot tell tag-based from label-based filtering without guessing.

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

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

There is no when-to-use guidance and no mention of alternatives such as vision_list_tickets (unfiltered) or vision_list_tickets_by_label. The trailing fragment "ticket / tag_search" is cryptic and reads like an internal resource path rather than a usage instruction, so it provides no actionable selection criteria.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that the result carries ids and names — useful but minimal; nothing about ordering, completeness, or behavior with an unknown department id.

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?

Very short and front-loaded, which is good, but it is written as two fragments and the second one ('ticket / get_ticket_type') is an unexplained reference that costs space without conveying actionable meaning.

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-only lookup with full schema coverage and no output schema, this is barely sufficient — the agent knows what it gets back (ids and names) and which department to scope by. It stops short of saying when this lookup is needed relative to the sibling list tools.

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

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

Schema description coverage is 100% and the single parameter department_id is documented in the schema, so the baseline applies. The phrase 'of a department' reinforces the filtering scope but adds no format or constraint detail 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 concrete resource and scope: the ticket types belonging to a specific department, plus what the payload contains (ids and names). The verb is only implied (the name supplies 'list'), and it doesn't contrast itself with the sibling lookups vision_list_priorities or vision_list_statuses, but an agent can still tell what it returns.

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, when-not-to-use, or prerequisite guidance. The trailing 'ticket / get_ticket_type' is a cryptic pointer to a related endpoint rather than a stated alternative, so the agent must infer that this is the lookup to call before populating a ticket-type id elsewhere.

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, openWorldHint=true and non-idempotency, so the safety bar is lower, but the description still adds value by surfacing the two client-facing effects (visibility and email) that must be deliberately chosen. It does not say whether the reply changes ticket status or what the response contains, but the side-effect disclosure is the important part for a destructive write.

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

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

The leading 'WRITE: confirm:true required' is well front-loaded, but the closing fragment 'ticket / reply_ticket.' is cryptic and reads as leftover notation rather than guidance, and the all-lowercase telegraphic style adds parsing cost without saving much space.

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

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

For a 6-parameter destructive write with no output schema, the definition covers the confirmation gate and both externally visible effects, which is the risky surface. It omits the return value and any note about the reply appearing in ticket history or triggering notifications beyond email.

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 earns above baseline by emphasizing intent for the two ambiguous booleans and restating that send_email defaults to false. It adds little for ticket_id/message/from, which the schema fully documents.

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 a staff reply to a ticket', preceded by a WRITE label that tells the agent this is a mutation. The purpose is unambiguous, but it never distinguishes itself from the sibling vision_add_ticket_note, which an agent could easily confuse with this tool.

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 supplies a real precondition ('confirm:true required') and instructs the agent to decide the two broadcast flags explicitly, which is useful invocation guidance. However, it gives no when-to-use/when-not guidance against the note-adding sibling, so the agent must infer which of the two write tools to pick.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no mention of match semantics (substring vs prefix), case sensitivity, or what an empty result means, which is the value it could have added.

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 first sentence is tight and front-loaded. The second sentence is a garbled fragment that does not earn its place and actively dilutes an otherwise clean 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?

This is a simple, well-annotated, fully documented read tool with no output schema, so little is required. The real gap is the intended routing to vision_list_clients, which is present only as an unreadable fragment, leaving the agent without the one piece of context that is not already in structured fields.

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%: 'text', 'limit', and 'offset' are each documented with bounds and defaults. The description's 'by name or email text' only echoes the existing 'text' parameter description, 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?

The first sentence gives a specific verb and resource ('Search clients') plus the two searchable fields (name, email), which is enough to distinguish it from a plain list. The trailing fragment 'client / list_clients.' gestures at a sibling but is too broken to serve as clean differentiation.

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 statement of when to use this versus vision_list_clients; the only signal is the malformed fragment 'client / list_clients.', which reads as truncated text rather than an instruction. An agent must guess that this tool requires a search term while the sibling does not.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description's real contribution is the repeated emphasis on EXACT matching, which tells the agent partial strings will not match, but it never says what happens if both parameters are supplied or what a result record contains.

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

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

Three short sentences, front-loaded with the lookup keys and the exact-match constraint. The final fragment is clipped and grammatically unclear ('ticket / get_tickets with a filter on...'), which costs a bit of precision but 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?

Annotations cover safety and the schema is fully documented, so the basics are present. What's missing for a search tool with no output schema is whether it returns full ticket objects or summaries, and how it behaves with zero or two lookup values — the agent is left to guess.

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 limit, offset, subject and ticket_hash are already fully documented with bounds and an example hash. The description only restates 'exact' for the two lookup fields and adds no new semantics (no combined-filter behavior, no match precedence) — 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 (find tickets) plus the two exact lookup keys, with an example reference (VHD-218). It hints at sibling overlap with get_ticket / get_tickets rather than drawing a clean line between them, so the reader still has to infer why this tool exists separately.

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 line 'Give one of them' does tell the agent to supply ticket_hash or subject, which is real usage guidance since neither is schema-required. But the closing phrase 'ticket / get_tickets with a filter on ticket_hash or subject' reads as an equivalence statement rather than a 'use X instead when Y' rule, and no when-not condition is given.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true; the description adds real context beyond them by declaring the write nature and mandatory confirm:true, and by disclosing the cascade that changing department can alter which statuses and priorities apply. It does not itself spell out the client-visible/email side effects (that lives only in the confirm param description) or whether the change is reversible.

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

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

Front-loads the critical 'WRITE: confirm:true required' warning and keeps the whole thing to a few dense clauses. The trailing fragment 'ticket / update_properties.' is cryptic and reads like leftover scaffolding rather than an earned sentence.

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 destructive 4-param mutation with no output schema, it covers the write confirmation, id-resolution prerequisite and the department cascade. Missing only a note on reversibility/rollback and what a successful call returns.

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, but the description earns a bump by explaining that value_id is an id that must be resolved via the list_* tools rather than a name, and by restating the property enum in human terms.

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

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

States a specific verb and resource ('change one property of a ticket to another id') and enumerates the four allowed properties, which cleanly separates it from siblings like vision_assign_ticket_staff, vision_add_ticket_tag and vision_add_ticket_note that also mutate a ticket.

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 an explicit prerequisite ('Look the ids up first (vision_list_statuses and the like)') and names the sibling lookup tools, plus a conditional warning about department changes affecting valid statuses/priorities. It stops short of stating when NOT to use this tool (e.g. tags/staff have their own tools), but the enumerated property list implies the boundary.

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