re-amaze

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

Annotations only declare destructiveHint=true, so the description carries most of the burden. It discloses nothing about authentication requirements, duplicate-email behavior, rate limits, or what the creation returns, and the REST endpoint reference adds no behavioral information an agent can act on.

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 verb+resource leads. It is arguably under-specified rather than padded, so it earns good marks for structure without reaching the top of the scale.

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 need not explain return values, and the schema fully covers the three parameters. However, for a mutating create tool with only a single destructiveHint annotation, it omits duplicate handling and any indication of success/failure behavior, leaving a noticeable 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 name, email, and the arbitrary custom-attribute 'data' object are already documented in the schema. The description adds no parameter detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Create a new contact') and clarifies the entity as the customer record via '(customer)', which separates it from conversation/article tools. It does not name the sibling operations it differs from (get_contact, list_contacts, update_contact), though 'new' implicitly excludes them.

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

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

There is no guidance on when to use this tool versus alternatives such as reamaze_update_contact, nor any mention of prerequisites (e.g. whether the contact must be unique by email, or what happens if it already exists). Usage must be inferred entirely from the tool 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?

Annotations carry destructiveHint=true but no readOnlyHint, and the description adds no behavioral context beyond the plain create statement — no auth/permission requirements, no side effects (e.g., outgoing email to the customer, tag/assignee handling), and no way to obtain the new conversation's ID for follow-up. With a mutation tool this leaves meaningful gaps.

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, front-loaded with the action and its key distinction ('with its first message'), plus the REST endpoint. Nothing is wasted.

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

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

For a 5-required-parameter mutation with no output schema, the description omits what the agent needs most: what the call returns (a conversation ID?) and how to use it in subsequent calls. The endpoint note is helpful but the definition is only minimally 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 each of the 9 parameters (including the status integer mapping and channel slug) documented in the schema itself. The description adds no 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?

The description states a specific verb+resource ('Create a new conversation') and adds scope detail — a support ticket created together with its first message, distinct from reamaze_reply_conversation. It does not explicitly name a sibling to contrast with, 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?

There is no when-to-use guidance: nothing says when to open a new conversation versus replying to an existing one (reamaze_reply_conversation), nor when to create the contact first (reamaze_create_contact). The agent must infer all routing from sibling names.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the underlying REST mapping (GET /articles/{slug}), which corroborates the read-only nature, but it says nothing about not-found behavior, auth requirements, 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?

Two short sentences with the purpose front-loaded; the REST endpoint line earns modest value as corroboration but is close to redundant 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?

A one-parameter get tool is nearly self-evident and annotations cover safety, but with no output schema the description could reasonably say what the article payload contains or what happens on a missing slug. Adequate, not 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 a single parameter and 100% schema description coverage, the baseline is 4. The description reinforces that the lookup is by slug, matching the schema, though it adds no format or sourcing detail beyond it.

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

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

States a specific verb and resource ('Get a single help-center article') and the lookup key (slug). The word 'single' implicitly separates it from reamaze_list_articles, but no sibling is named explicitly, 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?

There is no guidance on when to use this versus reamaze_list_articles, nor any prerequisite (e.g., slug discovery, auth scope). The only implied usage is 'you have a slug', which the agent must infer.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds only the underlying REST endpoint, which is structural trivia rather than behavioral context — no mention of what a missing slug/unknown channel returns or error behavior.

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

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

Two short sentences, front-loaded with the operation and followed by the endpoint. No wasted words, though the REST line is low-value filler for an agent that already has the endpoint mapping.

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?

Adequate for a trivial single-resource lookup, but with no output schema the description does not hint at the shape of a channel or error behavior. Minimum viable rather than complete.

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

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

Schema coverage is 100% and the single slug parameter is fully documented in the schema, so baseline 3 applies. The phrase 'by its slug' merely repeats the schema rather than adding format or sourcing detail.

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 channel by its slug') and distinguishes itself from the list_channels sibling by emphasizing singularity. The REST endpoint mapping confirms exact semantics, though no sibling is named explicitly.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. The description implies the caller must already possess a slug, but never says so or points to list_channels as the way to obtain one.

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 as a safe read, so the bar is lower. The description adds the REST mapping (GET /contacts/{identifier}), which is mildly useful, but says nothing about not-found behavior, error handling, 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, zero filler, with the core purpose front-loaded before the REST 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 single-parameter read tool with readOnlyHint covering the safety profile and no output schema required, the description is nearly complete; only the absence of any note on lookup failure behavior keeps it from a 5.

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

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

Schema description coverage is 100% and the single parameter already documents 'A contact email or id.' The description repeats that same 'email or id' detail without adding format or validation nuance, 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 ('Get') and resource ('a single contact (customer)'), and the qualifier 'single' implicitly distinguishes it from the sibling reamaze_list_contacts. An agent can tell this apart from list/update/create contact tools 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?

Usage is only implied by the word 'single' versus the list sibling; there is no explicit statement of when to prefer this over reamaze_list_contacts or reamaze_update_contact, nor any prerequisite/auth guidance. Adequate but with clear gaps.

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 nothing behavioral beyond it – only a REST endpoint mapping (GET /conversations/{slug}), which is not behavioral context such as error behavior or whether a missing slug 404s.

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 brief sentences with the core action front-loaded; nothing is padded. The second sentence is largely a redundant REST mapping but is compact enough not to hurt.

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 a fully covered schema and readOnlyHint annotation, the description plus structured data are nearly enough. No output schema exists, but the phrase 'a single conversation' adequately frames the return shape.

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 required 'slug' parameter is fully documented in the schema. The description restates 'by its slug' but adds no format, source, or lookup guidance, 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 conversation'), with the scope 'single' implicitly distinguishing it from reamaze_list_conversations. It stops short of explicitly naming the sibling it differs from, so it is clear but not fully 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?

Usage is only implied: retrieving by slug suggests you first need a slug, presumably from reamaze_list_conversations, but the description never says when to use this versus the list tool or other get_* siblings. No exclusions or prerequisites 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?

readOnlyHint=true already declares the safe-read profile, so the description is not obliged to restate safety. It adds only the REST endpoint mapping, and says nothing about pagination behavior (page_size/page_count are only in the schema) or result limits. Modest added value on top of 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 short sentences with no filler, and the core purpose is front-loaded ahead of the optionality note and endpoint reference. Every sentence 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?

For a two-optional-parameter, read-only list tool with no output schema, the description covers purpose, optionality, and the underlying API call. It is nearly complete; only pagination semantics for large result sets are left to the schema.

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

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

Schema description coverage is 100% for both parameters, which sets the baseline at 3. The description's 'all filters optional' reinforces that both are optional but adds no format or syntax detail beyond the schema's own 'title/body substring' and '1-based page number' notes.

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

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

The description states a specific verb (list/search) and resource (help-center/knowledge-base articles), and the GET /articles REST mapping pins it down further, making it easy to separate from reamaze_get_article. It stops short of explicitly naming the sibling it differs from, but the list-vs-get distinction is unambiguous.

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

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

'All filters optional' clarifies that no parameters are required, which is real invocation guidance. However, it gives no when-to-use/when-not guidance relative to siblings such as reamaze_get_article or reamaze_list_messages, so usage context 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, so safety is covered. The description adds the backing REST endpoint (GET /channels) and the downstream role of channel slugs, but says nothing about pagination behavior, ordering, or result size beyond what the schema's page description already 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?

Two sentences plus an endpoint reference, with the core purpose front-loaded and zero filler. Nothing could be removed without losing signal.

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

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

For a parameterless, read-only list tool with no output schema, the description covers what a channel is and why slugs matter. Minor gap: it does not describe the shape or scope of the returned list, which the agent must infer.

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

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

Schema description coverage is 100% for the single `page` parameter, which already documents 1-based paging and the page_size/page_count/total_count response fields. The description adds no parameter 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 and resource ('List channels') and clarifies the domain concept with concrete examples ('inboxes: email, chat, social, etc.'). It does not explicitly distinguish itself from the sibling reamaze_get_channel, though the list/get split is inferable from names.

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

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

It implies how the output is consumed ('Channel slugs are used as `category` filters') but never states when to call this versus reamaze_get_channel or why an agent would need the channel list. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that results are a single page (pagination semantics) and names the underlying REST endpoint, but does not cover page sizing, ordering, 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 clauses; the core operation leads, the optionality constraint follows, and the REST mapping is a compact trailing reference. No wasted words.

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 2-param read tool with no output schema, the definition covers the operation, optionality, pagination, and endpoint. Minor gaps (what page of what size by default) keep it short of 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 description coverage is 100%, so page and filter are already documented with examples. The description only restates that filters are optional, adding no syntax or format 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+resource (list/search contacts) and clarifies the resource is customers. It implicitly distinguishes from reamaze_get_contact (single contact) and reamaze_create_contact, though it doesn't name siblings 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; returns a page of contacts" tells the agent invocation is safe with no arguments and that results are paginated. However, it gives no explicit when-to-use-vs-get_contact guidance or conditions for choosing search over list.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds that it returns a page and that all filters are optional, which is modest additional context, but it says nothing about default page size, result caps, rate limits, or ordering defaults beyond what the schema states.

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

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

Three short sentences, front-loaded with the core action and definition, then scope and the REST endpoint. Zero filler.

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

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

For a zero-required, 10-param read tool with a full-coverage schema and a readOnlyHint, the definition is nearly sufficient. The only gap is that the schema description is the sole source for pagination details, which the description gestures at only vaguely ('returns a page').

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, including enum values and ISO8601 examples, so the schema carries the full burden. The description only restates that filters are optional and adds no format or interaction detail beyond it.

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

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

States a specific verb+resource and disambiguates the domain term by equating 'conversations' with 'support tickets', plus notes search capability. It doesn't explicitly differentiate from siblings like reamaze_get_conversation or reamaze_list_messages, but the resource is unambiguous.

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

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

'All filters optional' tells the agent the call works with zero args and that filters are additive, which is useful context. However, it never says when to use this versus reamaze_get_conversation (single item) or reamaze_list_messages, leaving the listing-vs-retrieval choice implicit.

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 by structured data. The description adds the useful non-obvious fact that the conversation slug goes in the PATH rather than the query, but says nothing about pagination behavior, default page size, or result ordering. Adds modest value beyond 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 sentences; the branch condition and endpoint mapping are front-loaded and the reader gets the core routing logic immediately. Efficient with no wasted prose, though 'Re:amaze REST.' is a low-value trailing fragment.

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 read-only list tool with a rich schema and no output schema; the essentials are present. Pagination semantics (page, page_size, total_count) and behavior of combined filters are only hinted at in the schema, so the description is adequate but far from complete for a 10-parameter retrieval tool.

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

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

Schema description coverage is 100%, so all 10 parameters are already documented in the schema (including the path-vs-query detail for conversation). The description adds no meaning beyond what the schema provides, 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 ('List messages') and distinguishes two retrieval scopes: conversation-scoped vs brand-wide, with the underlying endpoints named. It is clear and concrete, but does not differentiate itself from reamaze_list_conversations, which an agent selecting among siblings would need.

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

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

Gives an explicit conditional: use the conversation scope if a slug is provided, otherwise list brand-wide. This is clear context for when each path applies, though it omits guidance on the 8 optional filters (e.g. when to use start_date/end_date, tag combinations) and does not point to alternative tools.

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

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

The readOnlyHint annotation already establishes this is a safe read, and the description adds the underlying REST mapping (GET /staff). It discloses no pagination behavior or return shape, but with annotations covering the safety profile a 3 is appropriate for this simple list.

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

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

Two short sentences with zero filler, front-loading the resource before the REST endpoint detail. Every clause earns its place.

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

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

For a simple read-only enumeration with one fully documented parameter and a readOnlyHint annotation, the definition is nearly complete. It could mention the return format or pagination, but the absence of an output schema makes this a minor gap.

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

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

Schema description coverage is 100%, so the single 'page' parameter is fully documented in the schema (1-based, response reports page_size/page_count/total_count). The description adds nothing beyond that, so baseline 3 is 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?

States a specific verb and resource ('List staff (agent) accounts on the brand'), clearly distinct from sibling resources like contacts, conversations, and channels. It does not explicitly name an alternative sibling, but the resource itself is unambiguous.

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

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

Usage is only implied by the verb; there is no explicit when-to-use, prerequisite, or alternative guidance. For a straightforward enumeration tool this is minimally adequate, but nothing tells the agent when this is preferable to, say, a filtered contact or channel lookup.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden. It discloses the effect (a message is appended to an existing conversation) and the consequential visibility distinction between a customer-facing reply and an internal note, which is real operational context. It does not cover irreversibility, duplicate-send behavior on repeated calls, or permission needs.

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

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

Two sentences, zero filler: the effect and its two modes come first, the endpoint identifier last. Nothing is wasted or 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 an 8-parameter mutation tool with no output schema and only a destructiveHint annotation, the description adequately conveys effect and visibility semantics. It stops short of the mutation caveats an agent would want (repeat calls create additional messages, sends are externally visible and not recallable).

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

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

Schema description coverage is 100%, so every parameter including visibility's 0/1 mapping is already documented in the schema. The description's 'customer-facing reply or internal note' simply mirrors the visibility enum values and adds no syntax or constraint beyond the structured data. Baseline 3 applies.

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

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

States a specific verb ('Add a message') and resource ('existing conversation'), and explicitly scopes the two modes (customer-facing reply vs internal note). Combined with the REST endpoint, an agent can distinguish this from reamaze_create_conversation and reamaze_list_messages 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 phrase 'an existing conversation' implies a slug must already exist, which steers the agent away from create_conversation, and the reply/note split gives context. However, no named alternative or explicit when-not condition is given (e.g. use create_conversation for a new thread, list_messages to read).

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 useful detail that the date window is fully optional, but it says nothing about response size, aggregation granularity, time-zone handling, or whether the result is paginated — context that matters for a report tool with 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 sentences, front-loaded with the purpose and metric definition before the optionality note. The trailing REST endpoint reference ("GET /reports/response_time") is arguably noise for an agent selecting a tool, but it is a minor, cheap addition.

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 report, the description covers purpose, the metric definition, and optionality of inputs. With no output schema present, it does not describe the returned shape or units of the response time, which 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 description coverage is 100%, and both parameters carry ISO8601 format examples, so the schema does the heavy lifting. The description only restates optionality of the two dates, adding no format or semantic 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 ("get the response-time report") and defines the metric parenthetically as "how quickly conversations were answered," which removes ambiguity about what the report contains. It does not, however, distinguish itself from the sibling reamaze_report_volume beyond the name, so an agent must infer the difference.

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 "Both dates optional" but gives no when-to-use guidance, no prerequisites, and no mention of the sibling report_volume as the alternative for a different metric. The caller can guess it's for measuring agent/team responsiveness, but nothing is stated explicitly.

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 both date filters are optional and cites the underlying REST endpoint, but says nothing about aggregation granularity, timezone handling, or output shape. Modest added value against an already-covered safety profile.

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, the optionality constraint follows, and the REST endpoint is relegated to a trailing reference. Every sentence earns its place.

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

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

For a read-only, zero-required-parameter report tool there is little an agent needs beyond what is given, and 'counts over time' hints at the return shape absent an output schema. Remaining gaps are minor: no note on bucketing granularity or default window when dates are omitted.

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 ISO8601 dates documented in the schema, so the baseline is 3. The description's 'Both dates optional' reinforces requiredness but adds no format or semantic detail beyond what the schema already provides.

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

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

States a specific verb and resource: 'Get the conversation-volume report (counts over time).' The parenthetical defines the metric, which helps distinguish it from reamaze_report_response_time, though the distinction is only implied by the metric name rather than called out. An agent can identify what it does without opening the schema.

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

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

The note 'Both dates optional' tells the agent the call is valid with no arguments, which is useful invocation guidance. However, there is no explicit when-to-use instruction and no mention of the sibling report tool (response_time), so the agent must infer which report 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?

"Only provided fields change" is genuinely useful behavioral information that annotations do not convey, since destructiveHint=true alone does not tell the agent updates are sparse. However, it never explains the destructive aspect (any risk of overwriting/clobbering values) and the stated PUT endpoint conventionally implies full replacement, which sits at odds with the partial-update claim.

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, zero filler, with the core action and the partial-update constraint front-loaded before the REST routing detail. 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 four-parameter mutation with full schema coverage, no output schema and a destructiveHint, the description covers the essentials. It stops short of explaining the destructive semantics flagged in annotations, auth requirements, or how to clear an existing field value, and the PUT-vs-sparse-update wording leaves a small ambiguity.

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 id, data, name and email; the description adds only the sparse-update semantic for omitted fields. That is the baseline expectation when the schema does the heavy lifting, with no extra syntax or format detail contributed.

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

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

States a specific verb and resource ("Update fields on an existing contact") and qualifies it as targeting an existing record, which implicitly separates it from reamaze_create_contact. It does not name or contrast any sibling explicitly, so it lands just short of full sibling differentiation.

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

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

Usage is implied by "existing contact" plus the partial-update note, so an agent can infer this is for modifying a known contact rather than creating one. There is no explicit when-to-use/when-not guidance and no mention of prerequisites such as needing the contact id or prior lookup via reamaze_get_contact.

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 genuine value beyond that by clarifying that unspecified fields are preserved (no full-overwrite blast radius), but it does not mention permission requirements, whether history/audit is affected, or that tag_list replaces rather than appends.

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

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

Two tight sentences plus an endpoint reference; the mutation semantics are front-loaded before the API detail. Nothing is padding, though the trailing REST path adds little for an agent that already has the tool bound.

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 mostly flat, 6-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, partial-update behavior, and the underlying endpoint. Only the tag replacement semantics and hold_until linkage are left solely to the schema.

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

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

Schema description coverage is 100%, including the status integer legend and the hold_until dependency on status=5, so the baseline is 3. The description's field list largely restates schema names, and it omits hold_until and calls the parameter "tags" when the schema names it "tag_list".

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 (Update) and resource (existing conversation) plus the mutable field groups (subject, status, tags, assignee), which cleanly separates it from reamaze_create_conversation and reamaze_reply_conversation. It does not name those siblings, so an agent must infer the boundary rather than being told it.

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" usefully signals partial-update semantics, which is the main selection question for an update tool. There is no explicit guidance on when to prefer this over reamaze_reply_conversation or reamaze_create_conversation, and no prerequisites or exclusions are stated.

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