Query channels, search messages, and read threads, users and reactions in your Stream Chat app.
Scored across 13 tools
Most tools have clearly distinct resource+action targets (get vs query vs search vs send). Two pairs could be confused: stream_get_replies (replies for one parent message) vs stream_query_threads (list threads), and stream_get_channel, which despite its read-style name uses a get-or-create endpoint and may create a channel. Descriptions partially mitigate these overlaps.
Every tool uses the same stream_<verb>_<noun> snake_case pattern. Verbs are semantically consistent: get_* fetches a specific resource by id, query_* lists/filters a collection, search_* searches, and send_* performs a write. No mixed conventions or vague verbs.
13 tools is well within the ideal 3-15 range and each tool maps to a meaningful Stream chat API operation. The set is neither bloated with redundant variants nor thin enough to force workarounds for basic reads and sends.
Read coverage is broad (app, channels, messages, reactions, replies, threads, members, users, unread counts), and there are two write tools (send message, send reaction). However, no update or delete operations exist for messages, reactions, channels, or members, and there is no user creation or member management, so the lifecycle is notably incomplete for the domain.
Fetch the Stream app's settings and configured channel types. Good first call to confirm credentials and discover available channel types. GET /api/v2/app.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring the safety profile, the description adds useful behavioral context beyond annotations: it is a credential-verification / discovery call, and it reveals the underlying endpoint. It does not cover rate limits or return format, but the annotation carries the safety burden.
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 purpose, then usage, then endpoint. No filler, 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 zero-param, read-only tool with no output schema, the description covers purpose, usage, and roughly what is returned (settings and channel types). Slightly more detail on the returned shape could help, but nothing essential to correct 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?
Zero parameters, so there is no parameter semantics to document; baseline is 4. The description correctly implies a no-argument app-scoped call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Fetch) and resource (the Stream app's settings and configured channel types), which is clearly distinct from the resource-scoped siblings like stream_get_channel and stream_get_message. An agent can identify the app-level metadata role without opening a schema. It also pins the exact endpoint (GET /api/v2/app).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use it: 'Good first call to confirm credentials and discover available channel types.' That is concrete usage context rather than inference. It stops short of naming an alternative tool or stating when not to use it, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single channel's state (config, members) and its most recent messages. Note: uses Stream's get-or-create endpoint — for an existing channel it reads; if the type/id does not exist it may be created empty. POST /api/v2/chat/channels/{type}/{id}/query.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel id (the part after the type). | |
| type | Yes | Channel type, e.g. "messaging", "team", "livestream". | |
| messages_limit | No | Recent messages to return. Default 25. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a genuine side effect that the structured data does not: an unknown type/id may be created empty. That is valuable context exceeding the annotations. But it conflicts with readOnlyHint=true, since creation modifies state, so the behavioral picture an agent gets from annotations alone is wrong; disclosure is good, consistency is not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary outcome before the caveat, with no padding. The raw HTTP path 'POST /api/v2/chat/channels/{type}/{id}/query' is marginal value for an agent choosing a tool, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so adequately: config, members, and recent messages. It omits ordering/pagination behavior for the message list, but for a 3-param read with full schema coverage this is close to complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so type, id and messages_limit (default 25, max 300) are already fully documented in the schema. The description adds only that recent messages are returned alongside state; it explains no parameter beyond what the schema already says. 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 plus the returned payload: fetch a single channel's state (config, members) and its most recent messages. The singular 'single channel' implicitly separates it from the plural sibling stream_query_channels, but no sibling is named explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one important usage caveat (the get-or-create semantics: reads an existing channel, may create one empty if the type/id is new), which is real guidance. However it never states when to prefer this over alternatives such as stream_query_channels or stream_get_message, so the when-to-use routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single message by its id. GET /api/v2/chat/messages/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id. | |
| show_deleted | No | Include the message even if soft-deleted. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description carries a lower burden, but it adds essentially nothing beyond restating the read operation and pasting the REST path. It does not mention soft-deleted message behavior (the non-obvious effect of show_deleted) or permissions/visibility 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 short sentences, front-loaded with the action and resource, with zero filler. Every clause earns its place, though the REST path adds little for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the operation is a straightforward single-resource read whose safety profile is covered by readOnlyHint. The only material omission is any note on soft-deleted messages or access restrictions.
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 'id' and 'show_deleted' are fully documented in the schema. The description adds no semantics beyond that, which is the correct 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?
States a specific verb (fetch) and resource (a single message) plus the identifying key (id), which cleanly separates it from stream_search_messages, stream_query_threads, and stream_get_replies. It stops short of naming any sibling explicitly, 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?
Requiring an 'id' implies the tool is for when the caller already knows the message identifier, as opposed to searching or listing. However, no explicit when-to-use or when-not-to-use guidance is given, and no alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the reactions on a message. GET /api/v2/chat/messages/{id}/reactions.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id. | |
| limit | No | Max reactions. Default 50. | |
| offset | No | Pagination offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, so the description's obligation is to add context beyond that — and it adds none. It omits pagination behavior, ordering of results, and what a reaction record contains, which are the traits an agent would actually benefit from here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the purpose front-loaded and no filler. The trailing HTTP endpoint is redundant for tool invocation but harmless, which keeps it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated read with a fully documented schema and a readOnly annotation, the definition is barely sufficient. With no output schema, a note on the shape of a returned reaction or the result ordering would have closed the 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%, so id, limit (default 50), and offset are fully documented in the schema; the description adds no syntax, format, or constraint detail. 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 the reactions on a message'), which is enough to separate it from the write-side sibling stream_send_reaction. It does not explicitly name any sibling, but the read/write split is obvious from the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus stream_get_message or stream_get_replies, and no stated prerequisites (e.g., needing a valid message id in the current channel). The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the reply messages in a thread, given the parent message id. GET /api/v2/chat/messages/{parent_id}/replies.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max replies (<=300). Default 25. | |
| parent_id | Yes | Parent (thread-root) message id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered, but the description adds nothing beyond a restatement of the endpoint. It does not disclose ordering, pagination behavior for threads longer than the limit, or whether deleted/inaccessible replies are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action and the keying input immediately, with no filler prose. The trailing REST path is redundant for an agent but does not crowd out the useful content.
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 say something about the returned collection (ordering, whether it is paginated, how to fetch more than the limit). It covers the input side adequately but leaves the return contract entirely unspecified.
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 parent_id and limit (default 25, max 300) are fully documented in the schema. The description adds only the phrase 'parent message id', which restates the schema rather than adding format or edge-case meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetch) and resource (reply messages in a thread) plus the keying parameter (parent message id), which distinguishes it from stream_get_message and stream_query_threads by scope. It stops short of naming a sibling explicitly, so the differentiation is inferable rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance: nothing tells the agent to prefer this over stream_get_message when reading a thread, nor how it relates to stream_query_threads. Usage is only weakly implied by 'given the parent message id'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch total and per-channel unread message/mention counts for one user. GET /api/v2/chat/unread.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | User id to fetch unread counts for. |
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 usefully discloses the return shape (total plus per-channel, messages and mentions counts) and the backing endpoint, but says nothing about auth requirements, pagination, 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 sentences, front-loaded with the core action and scope, followed by the endpoint. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full schema coverage and no output schema, the description discloses enough: what is fetched, the granularity of the counts, and the endpoint. Minor gaps around return format details are acceptable given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter is fully documented in the schema, so the schema does the heavy lifting. The description's 'for one user' only echoes the parameter's intent without adding syntax or format 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 ('Fetch') and resource ('unread message/mention counts') with the exact scope ('total and per-channel ... for one user'). It is clearly distinguishable from siblings like stream_get_channel or stream_search_messages.
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 single-user scope implies when the tool applies, but there is no explicit when-to-use, no exclusion, and no mention of alternatives such as querying channels or messages for other count data. Usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/filter channels by a Stream query filter. e.g. filter {"type":"messaging"} or {"members":{"$in":["user-1"]}}. Returns channels with recent state. POST /api/v2/chat/channels.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Default [{"field":"last_message_at","direction":-1}]. | |
| limit | No | Max channels (<=30). Default 30. | |
| filter | No | Stream filter_conditions object, e.g. {"type":"messaging"} or {"members":{"$in":["u1"]}}. Default {} (all channels the app can see). | |
| offset | No | Pagination offset. | |
| message_limit | No | Recent messages per channel to include. Default 25. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safety profile, so the bar is lower. The description adds that channels come back 'with recent state' and cites the POST endpoint, but says nothing about ordering behavior beyond the schema defaults, pagination semantics, or result size 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 the core purpose front-loaded and examples adjacent. The trailing endpoint string adds little for an agent, but nothing is verbose 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?
A read tool with a rich 5-property schema and no output schema; the description sketches return content ('channels with recent state'). It is adequate, but it omits result shape, ordering guarantees, and how message_limit interacts with the payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented with defaults and bounds. The description's filter examples largely duplicate the filter property's own description, adding no meaning 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?
Clear specific verb+resource: 'List/filter channels by a Stream query filter', with concrete filter examples. It implicitly contrasts with the singular stream_get_channel, but never names or distinguishes itself from siblings such as stream_query_members or stream_get_channel 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?
The filter examples illustrate usage context, and 'Default {} (all channels the app can see)' is in the schema. However there is no explicit when-to-use versus stream_get_channel (single channel) or guidance on pagination/limits trade-offs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/filter the members of one channel. Requires the channel type + id. Optional member filter, e.g. {"name":{"$autocomplete":"jo"}}. GET /api/v2/chat/members.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel id. | |
| sort | No | Sort spec, e.g. [{"field":"created_at","direction":1}]. | |
| type | Yes | Channel type, e.g. "messaging". | |
| limit | No | Max members (<=100). Default 100. | |
| filter | No | Member filter_conditions, e.g. {"user_id":{"$in":["u1","u2"]}}. Default {}. | |
| offset | No | Pagination offset. |
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 reinforces the required inputs and names the underlying GET endpoint. It adds no detail on pagination behavior, result caps, or why a "stream_"-named tool returns a paged GET result rather than a live feed, which is a real ambiguity left unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the operation first, the prerequisite second, and a concrete example plus endpoint last. Nothing is redundant and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, fully-schema-documented list tool with no output schema, the description covers the operation, required inputs, filtering, and the backing endpoint. Only the ambiguous streaming-vs-paged behavior and result semantics remain unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (id, type, filter, sort, limit, offset) is already documented in the schema, including examples. The description quotes a filter example that duplicates the schema's own text, adding no meaning 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 ("List/filter the members of one channel") and scopes it to a single channel, which separates it from stream_query_channels and stream_query_users. It does not explicitly name or contrast a sibling, so it falls short of the top mark.
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 states a prerequisite ("Requires the channel type + id") and the intended operation, so usage is implied. It gives no explicit when-to-use vs when-not guidance and never mentions an alternative tool for broader member or user lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List threads (messages with replies). Server-side calls should pass a user_id to scope thread read-state to that user. POST /api/v2/chat/threads.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort spec for threads. | |
| limit | No | Max threads (<=25). Default 10. | |
| user_id | No | User id to scope thread participation/read-state to. | |
| reply_limit | No | Replies to preview per thread. Default 3. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safety profile, and the description adds the scoping behavior for user_id plus the underlying POST endpoint. It says nothing about pagination, ordering defaults, or result volume, so the added behavioral context is real but thin.
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 resource definition and followed by the one actionable constraint. The trailing endpoint path is marginally useful and slightly offsets the otherwise lean structure.
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, non-destructive query tool with full schema parameter coverage and no output schema, the description covers the essentials and adds the non-obvious scoping rule. Remaining gaps (pagination, default sort) are minor given the annotations and 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 sort, limit, user_id, and reply_limit are all documented in the schema and the baseline is 3. The description does add meaning for user_id by explaining why server-side callers must pass it (read-state scoping), but contributes nothing for the other three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List threads') and usefully clarifies that a thread is a message with replies, which distinguishes it from stream_get_message. It does not explicitly contrast with the closest sibling, stream_get_replies, so it stops 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?
Provides one concrete usage rule: server-side callers should pass user_id to scope read-state. That is implied-usage guidance rather than an explicit when-to-use/when-not framing, and it never tells the agent when to prefer stream_get_replies or stream_search_messages over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/filter users in the app. e.g. filter {"role":{"$eq":"admin"}} or {"id":{"$in":["u1"]}}. GET /api/v2/users.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort spec, e.g. [{"field":"created_at","direction":-1}]. | |
| limit | No | Max users (<=100). Default 100. | |
| filter | No | User filter_conditions, e.g. {"role":{"$eq":"admin"}}. Default {} (all users). | |
| offset | No | Pagination offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read; the description adds the GET /api/v2/users endpoint, which is mildly useful context. It discloses nothing about result size caps, defaulting, or ordering behavior beyond what the schema already 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?
One compact sentence plus an inline example and endpoint, front-loaded with the core action. The trailing 'GET /api/v2/users' is arguably noise for an agent that invokes the tool rather than HTTP, but it costs little.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description would ideally hint at the returned user shape, but it says nothing about the response. With full parameter coverage and a readOnly annotation, the definition is adequate for a simple list tool 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 description coverage is 100%, so filter/sort/limit/offset are already documented with examples. The description restates the filter example and adds an $in-style example, a marginal increment over the schema's $eq example, 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 ('List/filter users in the app') and the backing endpoint, so an agent knows it is a read query over the user collection. It does not distinguish itself from the nearby stream_query_members sibling, whose distinction from 'users' an agent would have to infer.
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 'List/filter users' but there is no explicit when-to-use, when-not, or named alternative (e.g. members vs users, or search tools for text matching). The agent must infer the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search messages across channels. Scope with a channel filter (filter, e.g. {"type":"messaging"}) plus EITHER a full-text query OR a message_filter object (e.g. {"text":{"$q":"refund"}}). GET /api/v2/chat/search.
| Name | Required | Description | Default |
|---|---|---|---|
| next | No | Pagination cursor returned by a previous search. | |
| sort | No | Sort spec for results. | |
| limit | No | Max results (<=100). Default 20. | |
| query | No | Full-text search string. Provide this OR message_filter. | |
| filter | Yes | Channel filter_conditions, e.g. {"type":"messaging"} or {"members":{"$in":["u1"]}}. | |
| message_filter | No | Message filter object, e.g. {"text":{"$q":"refund"}} or {"attachments":{"$exists":true}}. |
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 endpoint (GET /api/v2/chat/search) and the mixed query/filter requirement, but says nothing about pagination behavior, result caps, or rate limits despite the 'next' cursor in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the core scope stated first and the query/filter rule immediately after. The trailing API endpoint is minor but slightly non-essential padding for an agent that only needs invocation semantics.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter search tool with nested filter objects and no output schema, the description covers the required combination and the two key search modes. Pagination, sort, and limit are left entirely to the schema, which is acceptable but leaves a small 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 baseline is 3. The description repeats the examples already present in the schema for 'filter' and 'message_filter' rather than adding new meaning, offering no added semantic 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+resource ('Search messages across channels'), which clearly separates it from read-oriented siblings like stream_get_message and stream_query_threads. It is clear but does not explicitly name an alternative tool, so it stops 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?
Explicitly states the invocation constraint: scope with a channel 'filter' plus EITHER a full-text 'query' OR a 'message_filter' object. That EITHER/OR rule is genuinely actionable. It lacks when-not guidance and does not name alternative search paths, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚠️ WRITE: post a new message to a channel, attributed to user_id (must be an existing user in the app). POST /api/v2/chat/channels/{type}/{id}/message.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Channel id. | |
| text | Yes | Message text. | |
| type | Yes | Channel type, e.g. "messaging". | |
| user_id | Yes | Existing user id to send the message as. | |
| mentioned_users | No | User ids to @mention. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation destructiveHint=true already carries the safety profile, so the bar is lower. The description usefully adds a precondition (the sender must be an existing user) and the underlying endpoint, but says nothing about reversibility, rate limits, notification fan-out, or what happens to the message after posting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence led by a WRITE warning, then the action, the actor constraint, and the endpoint — no filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter write tool with full schema coverage and no output schema, the description covers the required inputs and the key precondition; the optional mentioned_users parameter and any return detail are left to the schema, which is acceptable given 100% coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema, establishing a baseline of 3. The description only restates the user_id precondition (already in the schema as 'Existing user id to send the message as') and mirrors type/id through the endpoint path, adding no new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource — 'post a new message to a channel' — which clearly separates it from the read-oriented get_*/query_* siblings. It does not, however, name the nearest alternative (stream_send_reaction) or otherwise explicitly differentiate from siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the WRITE marker and the verb 'post'; there is no explicit when-to-use/when-not guidance and no named alternative. The one precondition given ('user_id must be an existing user in the app') is a prerequisite rather than routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚠️ WRITE: add a reaction (e.g. "like", "love") to a message, attributed to user_id (must be an existing user). POST /api/v2/chat/messages/{id}/reaction.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Message id to react to. | |
| user_id | Yes | Existing user id to react as. | |
| reaction_type | Yes | Reaction type, e.g. "like", "love", "haha". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the write semantics, the exact endpoint (POST /api/v2/chat/messages/{id}/reaction), and the constraint that the acting user must already exist. It does not mention idempotency, duplicate-reaction handling, or required permissions, but for an additive write with destructiveHint already declared, this is solid 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?
A single tightly packed sentence that front-loads the WRITE warning, then the action, then the precondition, then the endpoint. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter write with no output schema, the description covers action, target, actor constraint, and transport endpoint. Only failure modes (duplicate reaction, invalid message id, permission errors) are unaddressed, which is a minor gap at this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (id, reaction_type, user_id) are already documented in the schema with examples and constraints. The description restates examples and the existing-user rule rather than adding new semantics, so the baseline of 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: adding a reaction to a message, attributed to a user. That is clearly separable from stream_get_reactions (read) and stream_send_message (message post), although no sibling is named explicitly, so differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It supplies a precondition (user_id must be an existing user) and flags the call as a WRITE, which is useful for correct invocation. It never says when to prefer a different tool or when not to call it (e.g. reacting vs fetching reactions), leaving usage implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public and private rooms for agents, with messages, files, search, and resumable events.
CometChat docs search + implementation bundles: add chat, voice, video & moderation to your app.
Read Bettermode community spaces, members and posts; full-text search across your community.
Read and verify freeq conversations: channels, history, search, signatures, pins.
Add one secure layer between your agents and this server.
