Re:amaze MCP by usefulapi

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

Annotations provide only destructiveHint=true, so the description carries most of the behavioral burden. It says nothing about what happens on duplicate email, whether the call is idempotent, what authentication is required, or what the response contains — all important for a create endpoint. No contradiction with annotations.

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

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

Two short sentences, front-loaded with the operation, with the REST endpoint as a compact implementation hint. Nothing is padded, though the endpoint line is informational rather than agent-directing.

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

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

For a three-parameter create tool with a fully documented schema and no output schema, the essentials are present. However, duplicate-handling and return-value behavior — the things an agent most needs beyond the schema for a create — are absent, leaving a gap.

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

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

Schema description coverage is 100%, so the schema already documents name, email, and the arbitrary `data` attribute bag. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

"Create a new contact (customer)" is a specific verb+resource, and the clarifying parenthetical plus the REST endpoint (POST /contacts) make the operation unambiguous against siblings like reamaze_update_contact and reamaze_get_contact. It stops short of naming those siblings explicitly, so it's clear but not maximally differentiated.

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 word "new" implies this is for contacts that don't yet exist, but there is no explicit guidance on when to use this versus reamaze_update_contact, reamaze_get_contact, or reamaze_list_contacts, and no stated prerequisites.

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

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

Annotations provide only destructiveHint=true, so the description carries the remaining burden and adds almost nothing: it does not say that creating a conversation may email the customer/recipients, whether it is idempotent, what happens on duplicate subject, or what auth scope is required. For a write tool with side effects (outbound notification), that is a real gap.

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

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

Two short, front-loaded sentences with no filler; the core action leads and the REST endpoint trails. The 'POST /conversations' fragment is mildly redundant for an agent but harmless and occasionally useful.

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 9 parameters, 100% schema coverage and no output schema, the schema side is covered, but the description omits the return value (presumably the created conversation/id) that an agent needs to chain a follow-up call. Nothing on side effects or failure modes either.

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

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

Schema description coverage is 100%, including the status enum mapping and which fields are required, so the baseline of 3 applies. The description adds no parameter-level detail beyond noting the message is the 'first message', which the schema already implies.

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

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

States a specific verb+resource ('Create a new conversation') and disambiguates the domain term by equating it with 'support ticket'. It also notes the tool creates the first message in the same call, which cleanly separates it from reamaze_reply_conversation and reamaze_create_contact.

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 is given: nothing tells the agent to prefer this over reamaze_reply_conversation when a conversation already exists, nor any prerequisite (e.g. the channel slug must already exist, customer may need to exist). Usage is only inferable from the name.

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

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

The readOnlyHint annotation already tells the agent this is a safe read. The description adds only the underlying REST mapping (GET /articles/{slug}), with no detail on 404 behavior, auth requirements, or return shape.

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

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

Two compact sentences, core action front-loaded, no filler. Every word contributes.

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?

A simple single-parameter read tool whose safety profile is covered by annotations; no output schema, so return values need not be explained. Adequate for correct invocation, though slightly more on missing-slug behavior would round it out.

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, and schema description coverage is 100%, so the schema fully documents 'slug'. The description restates that the lookup is by slug but adds no format or matching semantics 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 ('Get a single help-center article') and specifies the lookup key ('by its slug'), which separates it from the list_articles sibling. The distinction is implicit rather than naming an alternative explicitly.

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

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

Usage is implied by the requirement of a slug and the word 'single', which contrasts with the list tool. There is no explicit statement of when to prefer this over reamaze_list_articles or any prerequisite/error context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds essentially nothing behavioral beyond restating the REST verb/path — no not-found behavior, no error semantics, and no note on what a channel object contains.

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

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

Two compact sentences, front-loaded with the purpose and followed by the endpoint mapping. No padding or redundancy.

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

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

For a one-parameter read tool with full schema coverage and a readOnlyHint, the description is nearly sufficient. It lacks any hint about the returned channel shape or failure mode, but the task is simple enough that this 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 description coverage is 100% with a single, required, self-documenting 'slug' parameter, so the baseline of 3 applies. The description only confirms the slug identifies the channel and adds no format or source-of-value guidance 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 a specific verb ('Get') and resource ('a single channel by its slug'), and the word 'single' implicitly contrasts with the reamaze_list_channels sibling. It stops short of explicitly naming that alternative, so an agent must infer the distinction.

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

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

Usage is only implied: an agent can gather that this is the lookup path once a slug is known and that reamaze_list_channels is how slugs are discovered, but the description never states when to use this versus the list tool or what to do if the slug is unknown.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is established without the description. The description reinforces this with 'GET /contacts/{identifier}' and notes the identifier accepts email or id, but adds no behavioral traits beyond that — no error behavior for missing contacts, no pagination/return-shape notes.

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 core purpose comes first. The trailing REST endpoint reference is compact but largely redundant with the tool name and annotations, so not perfectly economical.

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 full schema coverage and a readOnlyHint annotation, the description covers what an agent needs to invoke it correctly. The absence of any note about the response shape is a minor gap given there is no output schema, but low risk here.

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 is fully documented in the schema. The description's 'identifier (email or id)' restates the schema rather than adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('a single contact (customer)') and clarifies scope with 'single', which implicitly distinguishes it from the sibling reamaze_list_contacts. An agent can tell this is a by-identifier retrieval rather than a listing without opening either schema.

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

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

Usage is implied: fetch one contact when you already have its email or id. There is no explicit when-to-use/when-not-to-use guidance and no named alternative (e.g., use reamaze_list_contacts to search when you lack an identifier), so the agent must infer the boundary itself.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds only the raw REST verb/path ('GET /conversations/{slug}'), with no mention of failure behavior, auth requirements, or what a missing slug yields. With annotations carrying the safety profile, this is thin added 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?

Two short sentences with the primary action front-loaded and no filler. The REST endpoint note is compact and useful for mapping to the upstream API.

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-identifier read tool with annotations covering safety and a fully documented parameter, the description supplies what an agent needs to invoke it. Absent an output schema, it could optionally hint at the returned conversation shape, but that gap is minor here.

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?

Single required parameter with 100% schema description coverage, so the schema already defines 'slug' as the conversation slug. The description repeats only that the lookup is by slug, matching the baseline for schemas that do the heavy lifting.

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

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

States a specific verb and resource ('Get a single conversation') plus the retrieval key ('by its slug'), and the word 'single' implicitly distinguishes it from reamaze_list_conversations. It stops short of naming the sibling explicitly, so it lands just under the top band.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives, but the combination of 'single' plus a required slug implies the lookup-by-identifier use case versus the list tool. The agent must infer the routing rather than read 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the safety burden is lifted. The description adds only the REST endpoint reference and confirms all filters are optional; it says nothing about pagination behavior (page_size/page_count), result ordering, or rate limits that a listing tool's caller would care about.

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 no filler; the purpose leads and the optionality note follows. The trailing REST endpoint reference is mildly redundant with the tool name but is a cheap, useful pointer for developers.

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, zero-required-parameter listing tool with full schema coverage and an annotation already declaring readOnlyHint, the description supplies everything essential to invoke it correctly. It falls short only on return-shape and pagination expectations, which is acceptable given there is no output 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 both parameters (page with its 1-based semantics and reported page_size/page_count/total_count, plus the free-text filter) are already fully documented in the schema. The description adds only the confirmation that "all filters are optional," which is baseline-level value beyond the structured fields.

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 pair (list/search) and a clearly identified resource (help-center/knowledge-base articles), and pins the underlying REST call GET /articles. It does not, however, distinguish itself from the sibling reamaze_get_article (single-article retrieval), so an agent must infer the scope difference from the name 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?

"All filters optional" implies this is the browse/enumerate entry point when you have no specific article in mind, which is useful context. But it never explicitly says when to use this versus reamaze_get_article, nor states any exclusions or prerequisites, leaving the key routing decision to inference.

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

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

readOnlyHint=true already declares this is a safe read, so the description only needs to add scope or constraints. It adds the underlying REST endpoint (GET /channels) and the cross-tool fact that returned slugs feed `category` filters, but says nothing about pagination behavior, result ordering, or volume of results. Modest added value over annotations.

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

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

Three compact clauses, zero filler, and the core purpose is front-loaded before the supplementary slug note and endpoint reference. Nothing could be cut without losing information.

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

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

For a simple read-only list tool with no output schema, the description covers what the resource is, how results are consumed downstream, and the endpoint. It could go slightly further on pagination expectations given there is no output schema, but an agent has enough to call it correctly.

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

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

Only one parameter (`page`) and schema coverage is 100%, so the schema already documents it fully with page_size/page_count/total_count semantics. The description adds no parameter detail. Baseline 3 for a fully-documented single-param schema.

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

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

Specific verb+resource ('List channels') with a clarifying gloss that channels are inboxes (email, chat, social), which removes ambiguity about what a 'channel' is. It also names the sibling relation implicitly (get_channel handles a single one). It stops short of explicitly contrasting with reamaze_get_channel, so not a full 5.

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

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

Usage is implied rather than stated: the tool lists channels, so you call it when you need channel enumeration. The note that slugs are used as `category` filters gives a downstream reason to call it, which is genuinely useful context, but there is no explicit when-to-use/when-not or named alternative.

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

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

Annotations already declare readOnlyHint=true, so safety is covered by structured data. The description adds modest context that results are paginated ('returns a page of contacts'), but says nothing about page size, default ordering, or result limits beyond that.

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

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

Three short sentences, front-loaded with the core purpose and the optionality constraint. The trailing 'Re:amaze REST: GET /contacts' is redundant detail that an agent gains little from, but nothing is bloated.

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 two-parameter read tool with no output schema, the description adequately signals it returns a page of contacts and that all filters are optional. Missing only result-shape or ordering hints, which are low-stakes here.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema (page is 1-based with page_size/page_count/total_count semantics, filter is a free-text substring). The description only restates optionality, adding no syntax or format detail beyond structured fields.

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/search) and resource (contacts), disambiguating with '(customers)'. It does not explicitly distinguish itself from the sibling reamaze_get_contact or reamaze_list_conversations, but the list-vs-get distinction is clear enough from the name and description.

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?

'All filters optional' implies a browse/search use case, but there is no explicit guidance on when to use this versus reamaze_get_contact (single lookup) or any create/update sibling. Usage is inferable from the verb but never stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results are paginated ('returns a page of conversations'), which is useful, but it does not disclose default page size or ordering 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, front-loaded clauses with zero filler. The core action leads, followed by the optionality note and the endpoint reference.

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

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

With no output schema, the description should carry more of the return-shape burden, yet it only says 'a page of conversations'. Combined with the endpoint mapping and full schema coverage it is functional, but a brief note on pagination fields or result ordering would round it out.

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

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

Schema description coverage is 100% across all 10 parameters, so the schema already documents filters, enums, and date formats. The description only restates that filters are optional, adding no new parameter semantics. 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/search conversations') and clarifies the domain with '(support tickets)'. It distinguishes itself from reamaze_get_conversation by implying a collection rather than one item, though it never names the 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?

'All filters optional' gives minimal context, and there is no guidance on when to use this versus reamaze_get_conversation (single) or reamaze_list_messages. Usage is implied by the name rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description's endpoint-routing detail is largely restated purpose rather than new behavioral disclosure. It says nothing about pagination limits, ordering, or result size beyond what the schema's `page` description already carries.

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 scope-switching rule before the endpoint details. The opening 'List messages.' mostly restates the title, but nothing is padded and the important conditional comes early.

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

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

For a read-only, 10-parameter list tool with no output schema, the description covers the essential branch (conversation vs. brand-wide) and confirms optionality. Pagination semantics live in the schema, so the main remaining gap is response shape/ordering, which is minor for a list endpoint.

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

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

Schema description coverage is 100%, so every one of the 10 parameters is already documented, including the note that `conversation` goes in the path. The description adds little parameter-level meaning beyond duplicating that routing rule, 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?

Names a specific verb (list) and resource (messages), then immediately disambiguates the two possible scopes: per-conversation vs. brand-wide, with the underlying REST endpoints. An agent can tell exactly what set of objects it will get, and can distinguish it from reamaze_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?

States the condition that switches behavior (supply `conversation` to scope to one conversation, omit it to list across the brand) and notes all other filters are optional, which is clear usage context. It does not explicitly point at sibling tools (e.g. list_conversations) as alternatives, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the brand-scoping constraint and the underlying REST endpoint (GET /staff), which is modest extra context but says nothing about pagination behavior or response shape.

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

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

Two short sentences, front-loaded with the purpose, with no filler. The endpoint mapping is slightly redundant but harmless.

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

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

For a trivial one-parameter read-only list tool with full schema coverage and annotations carrying the safety profile, the definition is essentially complete. Only the absence of any return-value hint (with no output schema) keeps it from a 5.

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

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

Schema coverage is 100% and the single page parameter is fully documented in the schema, including the fields responses report. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('List staff (agent) accounts') and scopes it to the brand, which distinguishes it from the contact/conversation listing siblings. It does not explicitly name a sibling it differs from, so it falls just 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?

No guidance on when to use this versus reamaze_list_contacts or other list tools, and no prerequisites or exclusions stated. Usage must be inferred from the name alone.

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

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

Annotations provide only destructiveHint=true, which the description never addresses or explains. The description does add genuinely useful behavioral context by framing the two modes (customer-facing vs internal note), which matters operationally, but it omits notification behavior by default, staff-vs-customer authoring implications, and any rate or permission constraints.

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

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

Two tight sentences with zero filler; the primary purpose is front-loaded before the endpoint reference. Every clause carries information an agent can use.

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 tool with full schema coverage and no output schema, the description covers the core purpose adequately and does not need to explain return values. It falls slightly short of complete because it never reconciles the destructiveHint annotation or explains default notification behavior, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100%, so all eight parameters are already documented at the field level, including the visibility enum meaning (0 = regular reply, 1 = internal note) and suppress_notifications. The description's reply-vs-note framing mirrors what the schema already says, adding little beyond the required baseline.

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

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

States a specific verb (add a message) and resource (an existing conversation), and elaborates on the two message modes (customer-facing reply or internal note). The word "existing" implicitly separates it from sibling reamaze_create_conversation, and the REST endpoint reference anchors the operation precisely.

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 mentions the two possible message modes, which hints at when each applies, but gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives like reamaze_update_conversation or reamaze_create_conversation. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the concrete REST endpoint (GET /reports/response_time) and notes the dates are optional, but it does not say what happens when they are omitted (default window) or anything about the read's cost/pagination.

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

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

Three tight sentences with the resource and metric front-loaded, optionality next, and the REST mapping last. Nothing is padded 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?

With no output schema, the description carries the burden of describing what comes back, and it never says what the report returns (per-period averages, conversation counts, shape). For a simple, annotation-covered read this is an acceptable but incomplete definition.

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 documents both date bounds with ISO8601 examples, so the baseline is 3. The description's 'Both dates optional' only restates the schema's required-list implication and adds no format or semantics beyond it.

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

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

The description states a specific verb and resource ('Get the response-time report') and even defines the metric ('how quickly conversations were answered'), plus the underlying REST call. It is clearly distinguishable in substance from the volume sibling, but it never names or contrasts that sibling explicitly, so it stops just short of 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 only guidance is 'Both dates optional', which is parameter mechanics rather than when-to-use direction. There is no indication of when to pick this report over reamaze_report_volume, nor what the default scope is when dates are omitted.

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

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

readOnlyHint=true already establishes this is a safe read operation, so the bar is lower. The description adds that both date params are optional and cites the underlying REST endpoint, but discloses nothing about return shape, time bucketing, aggregation granularity, or rate 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 short, front-loaded sentences with no filler. The core purpose comes first, then the parameter note, then the endpoint reference.

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

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

For a zero-required-param, read-only report with annotations covering safety, this is close to complete. It could say more about the returned time-series shape or default range when dates are omitted, which matters since there is no output 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 ISO8601 formats and semantics of start_date/end_date are already fully documented in the schema. The description only restates that both are optional, adding no new meaning beyond the structured fields. 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: 'Get the conversation-volume report (counts over time)', which tells the agent exactly what data comes back. The sibling reamaze_report_response_time covers a different metric, but the description never names it to sharpen the distinction, so it's clear-but-not-sibling-differentiating.

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?

'Both dates optional' gives implicit usage context (you can call it with no filtering at all). However, there is no guidance on when to prefer the volume report over reamaze_report_response_time or any exclusions, so usage is only inferred.

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

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

The annotation destructiveHint=true signals mutation risk, and the description usefully adds 'Only provided fields change', clarifying partial-update semantics that the annotation does not. However, it does not disclose whether updates are reversible, what validation failures look like, or any rate limits, leaving real behavioral gaps for a mutation tool.

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

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

Three short, front-loaded sentences: purpose, key semantic (partial update), then endpoint. No filler and the most decision-relevant fact comes 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 4-param mutation with no output schema, the definition covers identity, partial-update behavior, and the endpoint, but omits permissions, reversibility, and return shape. It is minimally sufficient to call correctly but not rich.

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 each parameter is already documented including the note that id goes in the path and the open-ended custom attributes object. The description adds nothing parameter-specific 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 clear verb+resource: update fields on an existing contact, plus the underlying REST endpoint PUT /contacts/{id}. Siblings like reamaze_create_contact and reamaze_get_contact are implicitly distinguished by 'existing' and 'update', but the description never names them 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 phrase 'existing contact' implies the contact must already exist, which mildly signals usage, but there is no explicit when-to-use vs reamaze_create_contact or reamaze_get_contact, and no mention of required permissions or prerequisites. Adequate but leaves the agent to infer the routing.

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

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

Annotations already declare destructiveHint=true, so the mutation risk is covered. The description adds the meaningful PATCH-style guarantee that unmentioned fields are preserved, but it omits what is irreversible (e.g., tag replacement behavior lives only in the schema) and any auth or concurrency caveats.

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

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

Two short sentences, front-loaded with the operation and field scope, plus a compact REST endpoint hint. No filler, though the PUT path duplicates information an agent rarely needs for invocation.

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 mutation with no output schema and full schema coverage, the description supplies the key semantic detail (partial update) and the endpoint mapping. It is adequate, though it could say more about irreversibility or permission needs to fully support safe invocation.

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 enum mapping for status, ISO8601 format for hold_until, and replace semantics for tag_list are all documented in the schema itself. The description only repeats the field list (subject, status, tags, assignee) and even omits hold_until, adding no meaning 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 ('Update fields on an existing conversation') and enumerates the mutable fields, so the agent knows exactly what operation this is. It does not explicitly contrast itself with siblings like reply_conversation or update_contact, but the resource and verb are distinct enough to disambiguate.

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?

'Only provided fields change' gives partial-update semantics, which implies this is the tool for edits rather than creation or replies. However, it names no alternatives and gives no conditions or prerequisites (e.g., permission or slug requirements) for choosing this over reamaze_reply_conversation.

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