Helpwise MCP by usefulapi

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

Annotations already declare destructiveHint=true and non-idempotent, and the description earns credit by giving that destructiveness concrete meaning: 'Notes cannot be deleted through this API.' It also discloses audience visibility (team-only) and the endpoint/version (POST /notes/add, V0). It stops short of disclosing auth or 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?

Three tight sentences with zero filler, front-loaded with the 'WRITE:' marker so the operation type lands first, followed by visibility, irreversibility, and endpoint in descending order of importance.

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-required-param mutation with no output schema, the description covers the essentials an agent needs: what it does, who sees it, that it is irreversible here, and the transport endpoint. It omits any note on permissions or response behavior, but with annotations carrying the safety profile this is close to 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% – message, inbox_id, and conversation_id are all documented in the schema with type constraints. The description adds no syntax, format, or id/value guidance 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 and resource ('add an internal note to a conversation') and immediately scopes it with 'Visible to your Helpwise team only; it is not sent to the customer,' which cleanly separates it from the customer-facing sibling helpwise_send_email. An agent can pick this over alternatives 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?

The internal-vs-customer-facing distinction gives clear context for when this tool is appropriate, and it is the natural counterpart to helpwise_send_email. However, it never names that alternative or states an explicit exclusion, so the routing is left partly 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 idempotentHint=true; the description adds value by explaining the actual idempotent behavior ('applying a tag already present changes nothing') and disclosing the downstream side effect that tags can trigger Helpwise automations. Endpoint hint (POST /tags/apply) is minor but concrete.

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 plus endpoint, front-loaded with the WRITE marker and the key constraint. No filler, and the most decision-relevant facts (write, source of ids, batch limit) appear first.

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 2-parameter mutation tool with full annotation coverage and full schema coverage, the description covers safety, idempotency, batching limits and the id source. The only gap is that with no output schema, it does not say what the 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 both arrays are already documented (1-10 tag ids, 1-25 conversation ids), giving a baseline of 3. The description adds the meaningful detail that valid tag ids come from helpwise_list_tags, which the 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 (apply) and resource (existing tags) with scope (up to 25 conversations) and a WRITE prefix that flags the mutation. It also names the sibling that supplies the ids (helpwise_list_tags), which cleanly separates it from helpwise_remove_tags.

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 the prerequisite (ids must come from helpwise_list_tags) and the context that tags drive Helpwise automations, so an agent knows why it would call this. It does not explicitly name helpwise_remove_tags as the inverse operation, so the routing guidance is clear but not exhaustive.

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 write/idempotent/destructive/open-world, so the bar is lower; the description still adds real value by flagging the 'WRITE:' nature up front and disclosing the notification side effect ('The assignee may be notified by Helpwise'). It doesn't mention that reassigning overwrites the previous assignee, which would have earned a 5.

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

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

One front-loaded sentence carrying the WRITE marker, the operation, the unassign convention, and the id source, followed by the endpoint path. Nothing is wasted and the most important qualifier leads.

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 mutation semantics, the unassign path, id sourcing, a side-effect warning, and the API endpoint; with no output schema and full schema coverage there is little else required. The only gap is not clarifying what happens to a prior assignee on reassignment.

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 schema itself documents inbox_id, conversation_id, and the '0 to unassign' semantics of assigned_to. The description reinforces the unassign convention and adds the id source for assigned_to, but contributes little beyond the already-complete schema.

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

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

States a specific verb and resource ('assign a conversation to a team member') and explicitly covers the inverse operation (unassign via assigned_to 0). No sibling tool overlaps with assignment, so an agent can route here unambiguously.

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

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

Gives clear operational context: where to get the assignee id (helpwise_list_users) and how to unassign (assigned_to 0). It does not state when to prefer this over, say, helpwise_close_conversations or add_note, but for a single-purpose write tool that is a minor omission.

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, idempotentHint=true and readOnlyHint=false. The description goes beyond that by disclosing reversibility via helpwise_reopen_conversations and confirming no customer-facing notification — exactly the context an agent needs before invoking a destructive op.

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 clauses, front-loaded with the 'WRITE:' marker so the mutation nature is visible immediately. Every clause carries distinct information (scope, reversibility, side effects, endpoint) with no filler.

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

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

For a single-parameter mutation with full annotation coverage and no output schema, this covers scope, reversibility, and side effects adequately. Minor omission: it doesn't state the effect of closing an already-closed conversation, though idempotentHint partly covers that.

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 there is a single parameter, so the schema already documents the array, its item type, and the 1-25 bounds. The description's 'up to 25' reinforces maxItems but adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('close up to 25 conversations'), gives the scope limit, and clarifies intent with '(mark them done)'. It also names the sibling helpwise_reopen_conversations, so an agent can place it precisely among the 21 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?

Provides clear context for selecting this tool over siblings: it names the undo path (reopen) and asserts 'Nothing is sent to customers', which distinguishes it from helpwise_send_email or helpwise_add_note for a superficially similar end state. No explicit 'when not to use' statement, but the routing signal is strong.

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 idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by clarifying the side-effect boundary ('Nothing is sent to the person') and the consequence of non-idempotency ('creating the same email twice may create a duplicate'). It stops short of naming the endpoint requirement around permissions or the returned object.

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?

Extremely dense: a leading 'WRITE:' marker front-loads the operation type, followed by two short sentences and an endpoint tag. No sentence is padding and nothing important is buried.

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

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

For a 7-param write tool whose annotations cover write/destructive/non-idempotent, the description supplies the missing behavioral context (no notification, duplicate risk) and the endpoint. With no output schema, it would be more complete if it indicated what is returned (e.g., the new contact id) for follow-up calls.

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

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

Schema description coverage is 100%, so every one of the 7 parameters is already documented in the schema; baseline is 3. The description's parenthetical field list (name, company, job title, emails, phones, custom fields) merely restates schema properties without adding format, default, or cardinality 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 ('create a new contact in Helpwise') and enumerates the fields it accepts, plus the underlying endpoint POST /contacts. The verb alone cleanly separates it from siblings like helpwise_update_contact, helpwise_get_contact, and helpwise_list_contacts.

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

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

Usage is implied by 'create a new contact' and the duplicate caveat hints at a pre-check, but the description never says when to use this vs. helpwise_update_contact or helpwise_search_contacts. No explicit prerequisites or exclusion conditions 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?

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine value by disclosing the payload shape, including that 'recent conversations' are pulled in as part of the response — useful scope information not derivable from the schema, especially since there is no output schema.

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

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

Two short, front-loaded sentences with no filler; the return-content summary comes first. The second sentence is mildly redundant with the tool name but cheap and unambiguous.

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 tool with safety annotations but no output schema, the description compensates by describing the returned fields. Only the absence of routing guidance against the search/list siblings keeps it from being fully complete.

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

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

With one parameter (contact_id) at 100% schema description coverage, the schema already documents it fully. The description adds only the 'GET /contacts/{id}' hint that the id is a path parameter; no format, range, or lookup guidance beyond the schema's exclusiveMinimum/maximum.

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

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

States a specific resource (a single contact) and enumerates what it carries — emails, phones, company, custom fields, recent conversations — plus the underlying route GET /contacts/{id}. This distinguishes it implicitly from list_contacts and search_contacts, though it never names those 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?

No when-to-use guidance at all: nothing says to pick this over helpwise_search_contacts or helpwise_list_contacts, and no prerequisite (e.g. needing a known contact_id) is stated. The get-by-id semantics are only inferable from the name and the URL template.

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 genuine beyond-annotation context: the returned payload includes messages, notes, drafts, assignment and contacts, and it discloses pagination behavior via `page_token` from the previous reply.

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 payload contents before pagination and the endpoint. It is tight, though the trailing REST path is largely redundant with the tool name and title.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by enumerating the payload contents. Pagination is addressed; folder/limit defaults are left to the schema, which is acceptable given full schema coverage.

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 five parameters. The description only restates pagination for `page_token` and adds no syntax or semantics beyond what the schema provides, making the baseline 3 correct.

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

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

The description names a specific resource ('One conversation') and enumerates its contents (messages, notes, drafts, assignment, contacts), which distinguishes it from bulk operations. It is clear what it retrieves, though it never explicitly contrasts itself with the sibling helpwise_list_conversations.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The only procedural hint is how to page with `page_token`, leaving the get-vs-list choice to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond that: it identifies the resource as the API-key owner (an identity-scoped read) and discloses the underlying endpoint POST /users/me (V0), which explains why a POST is non-destructive.

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

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

Two compact sentences, zero filler; the returned resource is front-loaded and the endpoint/version note follows. Nothing is redundant with 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-parameter, read-only identity tool with no output schema, the description supplies the essential facts: what entity is returned, its fields, and the backing endpoint. Only the concrete response shape (e.g. JSON envelope) is unstated, which is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description does add value by enumerating the returned identity fields in the absence of an output 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 exactly what is returned: the Helpwise user tied to the calling API key, with the fields name, email and id. That distinguishes it from sibling user/contact lookups like helpwise_list_users or helpwise_get_contact, though it phrases the action as a noun rather than 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?

Usage is implied by 'the API key belongs to' – call this when you need the authenticated identity rather than a specific user lookup. However, no alternative is named (e.g. list_users for other users) and there is no explicit when/when-not statement.

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 needs no restating. The description goes beyond that by disclosing report semantics: change vs the previous period, per-day message breakdowns, busiest hour/day, and that it maps to GET /reports. It says nothing about rate limits or pagination, but the added content is substantive.

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

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

Front-loaded with the purpose, then a dense but scannable enumeration of report contents, closing with the filter note and endpoint. Nearly every clause earns its place, though the metric list is long enough to verge on inventory dump.

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 compensates by enumerating the report's return contents — counts, time series, averages, CSAT, per-agent rows. For a read-only analytical endpoint whose safety is covered by annotations, that covers what an agent needs before calling.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema itself, including the date formats and the business-hours flag. The description only restates that inbox and tag filters are optional and adds no syntax or defaults beyond the schema — the correct baseline when structured data carries the load.

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 (get) and resource (report) and enumerates the report's contents in detail — conversation counts, message volume, response/resolution times, CSAT, per-agent performance. It clearly identifies itself as a reporting tool, but never names or distinguishes itself from the sibling helpwise_get_tags_report, so an agent reading only the description must infer the split.

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 note 'Optional inbox and tag filters' implies when scoping makes sense, but there is no explicit when-to-use guidance and no routing against the obvious alternative, helpwise_get_tags_report. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the REST path 'GET /tags/{id}', which conveys no behavioral context such as error/404 handling or authorization requirements for a read of tag data.

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

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

Two short sentences with the purpose front-loaded and nothing wasted. The endpoint path is mildly redundant with the tool name but still informative, and the description is arguably undersized rather than padded.

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

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

For a single-parameter read tool with annotations covering safety, this is close to sufficient, but there is no output schema, so the description could say what a returned tag contains. That omission is the main remaining 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 coverage is 100% and the single tag_id parameter is fully documented in the schema ('Helpwise tag id.', positive integer). The description's 'by id' 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?

States a concrete verb+resource ('One tag by id'), which clearly differs from the sibling helpwise_list_tags. It stops short of naming the sibling or the collection endpoint explicitly, but the singular 'one tag' scope makes the distinction inferable.

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

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

Usage is implied by 'by id' — fetch a single tag when you already have its id — but there is no explicit when-to-use guidance, no mention of the list alternative, and no indication of what happens for an unknown id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the returned metric set, which is useful behavioral context, but says nothing about permissions, limits (e.g., max 20 tag_ids), or pagination of the report.

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

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

A single dense sentence that front-loads the resource and scope, followed by the returned metric list. Every clause earns its place; the trailing HTTP 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?

No output schema exists, and the description compensates by enumerating exactly what the report returns, which is the main thing an agent needs. Combined with a fully specified input schema and read-only annotations, it is complete enough, though it does not mention the 20-tag cap or truncation behavior.

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

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

Schema description coverage is 100%, so all five parameters (inbox_id, start, end, tag_ids, business_hours_only) are documented in the schema itself. The description reinforces the inbox/date-range scope but adds no format or semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('per-tag report for one inbox and a date range') and enumerates the metrics returned (conversations per tag, share, open conversations, average response, first-response, resolution time). This clearly distinguishes it from the generic sibling helpwise_get_report by naming the per-tag dimension and the inbox scoping.

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 framing ('for one inbox and a date range'), which tells the agent the required scope, but there is no explicit when-to-use vs helpwise_get_report or other report siblings, nor any exclusions. Adequate but leaves the agent to infer the choice.

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 usefully adds the returned field set and states pagination is via limit/offset, but says nothing about total counts, ordering, or result caps beyond what the schema covers.

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 fragments, front-loaded with the resource and its returned fields, then pagination, then the endpoint. Nothing is wasted, though the bare 'GET /contacts' line contributes little to an agent that never sees the raw HTTP layer.

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 compensates by naming the fields returned and explaining paging, which is the right call for a list endpoint. It stops short of noting ordering or whether a total/next_offset is returned, but the essential call-time 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 both parameters carry their own defaults, ranges, and the next_offset chaining hint, so the schema does the heavy lifting. The description only echoes 'Page with limit and offset' and adds no format or semantics beyond it. Baseline 3 applies.

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

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

States a specific verb+resource ('List contacts') and enumerates the returned fields (name, company, job title, emails, phones, id), so the agent knows exactly what this returns. It does not, however, distinguish itself from the sibling helpwise_search_contacts, which an agent could easily confuse it with.

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 helpwise_search_contacts, helpwise_get_contact, or filter-based alternatives. Browsing semantics are only implied by the word 'List' and the pagination note, leaving the agent to guess which sibling 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 and destructiveHint=false, lowering the bar. The description adds useful context beyond that: results are newest-first, folder defaults to 'all', pagination is token-based, and it exposes the raw endpoint GET /conversations. It still omits rate limits or result-size caveats, so not a 5.

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

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

Four tight sentences, front-loaded with the core verb+resource, then folder/pagination guidance and the endpoint. Every sentence carries information; nothing is boilerplate.

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

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

With no output schema, the description usefully enumerates the returned fields (subject, snippet, tags, assignee, flags, contact) and covers sorting, default folder behavior, and pagination. 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: it notes the folder defaults to 'all', clarifies that the page_token is the prior reply's next_page_token (bridging the schema's differently-named page_token field), and tells where inbox_ids come from.

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 conversations (threads) of one or more inboxes') and enumerates the returned fields, so the agent knows exactly what it gets. It references helpwise_list_inboxes as the source of ids but does not distinguish itself from helpwise_get_conversation or the search siblings, so sibling differentiation is only partial.

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 operational guidance (pick folder, default all, page with next_page_token, ids come from helpwise_list_inboxes) that implies how to invoke it. However it never says when to use this vs. alternatives such as helpwise_get_conversation for a single thread, so 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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by listing the return fields (id, name, address, type) and the endpoint, though it does not mention pagination behavior or auth requirements.

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

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

Three short sentences: purpose and return fields first, then downstream usage, then endpoint. Every sentence earns its place and the description is front-loaded.

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

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

With no output schema, the description appropriately lists the returned fields and endpoint, which an agent needs. It does not describe pagination behavior or response envelope details, but the schema covers the pagination parameters, so this is nearly 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%, with both page and limit parameters documented including defaults and ranges. The description adds no parameter details, so the baseline of 3 is appropriate.

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

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

States a specific verb (List) and resource (account's inboxes/mailboxes), and names the returned fields. Since no sibling tool lists inboxes, an agent can distinguish it from list_contacts, list_conversations, etc. by resource 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?

The description says 'Use the ids in the other tools,' which is downstream guidance rather than an explicit when-to-use statement. It does not name alternatives or exclusions, though no sibling tool lists inboxes, so usage is implied when inbox IDs are needed.

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 real value by naming the response fields and the underlying endpoint (GET /tags), but says nothing about pagination, auth, or result size limits.

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

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

Three terse fragments, front-loaded with the resource and its fields, with zero filler. The parenthetical field list is dense but readable and every element carries information.

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

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

With no output schema, the description takes on the burden of describing the return shape and does so by listing the fields. Combined with annotations covering the read-only safety profile, an agent has enough to call it correctly; only pagination and volume behavior are 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax or meaning that needs explaining. Nothing in the description misleads about inputs.

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

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

The description states a specific resource (all tags) and enumerates the returned fields (id, name, colour, parent, inbox), which is more than a bare restatement of the title. It implicitly distinguishes itself from the singular helpwise_get_tag via 'All tags', though it never names that sibling explicitly.

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

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

It tells the agent what to do with the output ('Use the ids with helpwise_apply_tags'), which is genuinely useful downstream routing. However, it gives no guidance on when to choose this over helpwise_get_tag or helpwise_get_tags_report, so the selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds inbox scoping and the underlying endpoint, but does not describe pagination, result limits, or whether missing inboxes error 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 short sentences that are front-loaded with the resource and scope, list the returned fields, and then state the downstream use. 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?

There is no output schema, but the description names the returned fields (id, name, email), which is the key missing piece an agent would need. Minor gaps remain around pagination and error behavior, but the definition is largely sufficient for a one-parameter read tool.

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

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

Schema coverage is 100% for the single inbox_id parameter, so the schema carries the documentation burden. The description implies the inbox scoping but adds no format or constraint detail beyond what the schema already states. Baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (team members/agents with access to an inbox) plus the returned fields (id, name, email), which cleanly distinguishes it from helpwise_get_current_user and helpwise_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?

The description gives a follow-up workflow link (use the ids with helpwise_assign_conversation) but no when-to-use condition or exclusion relative to the other user-adjacent siblings like helpwise_get_current_user. 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: the tags are not themselves deleted, and the operation is capped at 25 conversations. It stops short of describing response shape 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?

Three short clauses, mutation type front-loaded, scope and side-effect clarification immediately after, endpoint last. Zero wasted words and nothing important buried.

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

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

For a two-parameter mutation with no output schema and full annotation coverage, the description supplies the essentials: operation type, batch bound, and the key side-effect caveat. Only error/partial-failure behavior is unaddressed, 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 coverage is 100%: both array parameters carry min/max item constraints and per-field descriptions (1-10 tags, 1-25 conversations). The description's 'up to 25 conversations' mirrors the schema rather than adding new meaning, 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 ('take tags off') and resource ('conversations'), matching the title. It is clear and distinguishable from the inverse sibling helpwise_apply_tags by intent, but never names that sibling explicitly, so it stays at 4 rather than 5.

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

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

The description implies usage via the batch cap ('up to 25 conversations'), which tells the agent this is a bulk operation. However, it gives no explicit when-to-use guidance, no prerequisites, and does not contrast with helpwise_apply_tags or note what happens on partial failures.

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, readOnlyHint=false, and idempotentHint=true. The description adds valuable context beyond these: 'Nothing is sent to customers' clarifies a common worry for a conversation-mutating tool, and states the effect (moves back to inbox). The destructive nature is not fully explained, but the customer-facing safety note is meaningful added value.

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

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

One compact sentence with WRITE prefix, effect, side-effect clarification, and endpoint. Front-loaded and zero 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 single-parameter batch mutation, the definition covers purpose, limit, side-effects, and endpoint. It lacks return-value detail and any permissions/error context, but no output schema exists so the gap 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?

Schema coverage is 100% and the single parameter (conversation_ids, 1-25) is fully documented in the schema. The description's 'up to 25 conversations' merely restates the maxItems constraint rather than adding syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb (reopen/move back to inbox) and resource (conversations), with the batch limit (25). Clearly distinguished from its sibling helpwise_close_conversations, the inverse operation.

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

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

Implied usage (reopen closed conversations) is clear against the close sibling, but there is no explicit when-to-use or when-not guidance, no preconditions, and no mention of alternatives. Adequate but leaves inference to the agent.

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 safety is covered. The description adds only the endpoint (GET /contacts/search) and pagination shape; it says nothing about match semantics (exact, prefix, fuzzy) or result ordering, which are the traits an agent would actually need.

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

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

Three short, front-loaded sentences with the core purpose first and no padding. The trailing 'GET /contacts/search' line is largely redundant with the readOnly annotation, keeping it from a full 5.

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

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

For a simple filtered-list read tool with no output schema, this covers the essentials: what to search on, how to page. The gap is minor - the agent gets no hint about the shape of returned contacts or how next_offset surfaces, though the offset param description partly compensates.

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

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

Schema description coverage is 100%, so all three parameters (term, limit, offset) are already documented with ranges and defaults. The description's 'Page with limit and offset' merely restates that, adding 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?

States a specific verb and resource ('Search contacts') plus the matchable fields (name, email, phone), so the agent can distinguish it from get_contact or list_contacts. It does not name those siblings explicitly, so it stops short of a 5.

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

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

Usage is only implied: a term-based search tool versus list_contacts or get_contact for direct retrieval. The description adds pagination mechanics ('Page with limit and offset') but no explicit when-to-use, when-not-to-use, or alternative-routing guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, but the description adds real operational context they don't carry: irreversibility ('once sent it cannot be recalled'), the aggregate recipient cap (10 across to+cc), one-message-per-call semantics, and that the plain-text body is rendered as HTML. This is exactly the value-add expected when annotations 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?

Dense but front-loaded: the write/irreversible warning comes first, then constraints, then the new-vs-reply distinction, then the endpoint. Every sentence carries a distinct constraint; nothing is redundant padding.

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 high-risk mutation with no output schema, the description covers irreversibility, recipient limits, and message semantics thoroughly. It stops short of stating what the call returns or any permission/scope requirement on the inbox, but the critical call-correctness 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%, so the baseline is 3. The description goes beyond it by stating the combined cap of 10 recipients across to+cc — a cross-parameter constraint the JSON schema cannot express (maxItems would allow up to 19) — and by explaining the body's plain-text-to-HTML conversion. It adds genuine meaning without restating individual field descriptions.

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 — sending a real email from a named Helpwise inbox to given recipients — and explicitly distinguishes itself from the closest sibling behavior by noting it starts a new message rather than replying on a conversation (contrast with helpwise_add_note). An agent can route correctly 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 explicit exclusions and conditions: 'never use it for lists or campaigns', 'one message per call', 'this starts a new message (it is not a reply on an existing conversation)'. That is when-not-to-use guidance tied to named alternatives, not vague implication.

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?

Adds substantial behavior beyond the annotations: PUT requires a read-then-write of current values, passing emails/phones/custom_fields REPLACES the existing lists (a real data-loss trap), and 'Nothing is sent to the person' clarifies external side effects. Annotations only say destructive/idempotent/not-readonly; the description explains why and how.

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 dense sentences plus an endpoint token; the critical warning (WRITE, list replacement) is front-loaded. Slightly redundant to repeat the replacement semantics per list and to append the raw 'PUT /contacts/{id}' path, but no sentence is wasted.

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

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

For an 8-parameter mutation tool with full schema coverage, no output schema, and annotations covering the safety profile, the description closes the remaining gaps: read-modify-write mechanics, destructive list replacement, and absence of outbound messages. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and each array parameter already documents 'replaces the current list', so the description largely restates that. It adds no syntax, format, or edge-case meaning beyond the schema, so the baseline 3 is appropriate.

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

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

Opens with "WRITE: change a contact's name, company, job title, emails, phones or custom fields" – a specific verb plus resource plus the exact mutable field set. The WRITE marker and 'change' clearly separate it from read siblings like helpwise_get_contact and helpwise_list_contacts.

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

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

Usage is implied rather than stated: the WRITE label and field enumeration signal 'use this to modify an existing contact', but the description never explicitly contrasts with helpwise_create_contact or helpwise_get_contact, nor states prerequisites such as needing the contact to already exist. Adequate but with a clear routing gap.

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