DevReply

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

Annotations only cover the safety profile (mutating, non-idempotent, not destructive); the description adds genuinely non-derivable behavior: the note is invisible to the user, is attributed in the inbox as written by this agent, and renders Markdown. It omits duplicate behavior (annotations say non-idempotent, so re-posting creates another note) and any auth/permission expectations.

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 dense sentence, front-loaded with the resource and its visibility constraint, then the rendering/attribution detail. Nothing is wasted and nothing important is buried.

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

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

For a simple two-parameter tool with full schema coverage, an output schema, and annotations covering safety, the description supplies the remaining essentials: visibility to the end user, attribution, and supported formatting. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, with both parameters documented and the text param already carrying a Markdown example, so the schema does the heavy lifting. The description's mention of Markdown constructs largely restates what the schema already says, 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 exactly what is created — an internal note on a conversation — and immediately marks the scope that separates it from user-facing siblings: 'for the team only: the user never sees it.' An agent can tell this apart from reply_to_user or send_feedback 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?

It gives clear situational context for use ('internal', 'the user never sees it'), which tells the agent when this note type is appropriate versus a user-visible message. It stops short of naming an explicit alternative or stating exclusions, so it does not reach the when/when-not/alternatives bar of a 5.

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 non-read-only, non-idempotent, non-destructive, and closed-world. The description adds two things beyond that: the resulting public key is 'permanent', and the caller must be an owner. It doesn't cover failure modes or whether an existing platform can be re-added, but it meaningfully extends the annotation picture.

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 tight sentence front-loads the action and resource, then tacks on the side effect and the access constraint. Every clause earns its place with no redundancy.

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

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

With an output schema present, return values need no explanation, and all three parameters are fully covered by the schema. The description supplies the key persistence and owner-only constraint, leaving only edge cases like duplicate platform handling unaddressed.

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 app_id, platform, and bundle_id are already documented, including the enum and the 'optional when there is only one' note on app_id. The description's 'iOS, Android or web' merely restates the enum and adds no format or constraint 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?

The description states a specific verb and resource ('Adds iOS, Android or web to an app') and adds the key side effect, which cleanly separates it from siblings like create_app or update_app. An agent immediately knows this attaches a platform to an existing app rather than creating one.

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 prerequisite 'Owners only' gives useful access guidance, but there is no explicit when-to-use vs alternatives (e.g. add_platform vs create_app vs set_ios_push_key) and no when-not-to-use conditions. Usage is only implied by the purpose.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety bar is partly covered. The description adds real value beyond that: the authorization requirement ('Owners only'), the single-platform starting state, and what the call yields (public key, setup guide link).

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, no filler, with the core action and the platform-routing constraint front-loaded. The opening noun phrase is slightly telegraphic but the title supplies the verb, so it costs nothing.

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?

An output schema exists, so return values need not be enumerated, yet the description still flags the public key and setup guide link. Combined with the Owners-only caveat and the add_platform pointer, an agent has everything needed to invoke it correctly; only edge cases like name collisions or errors are unaddressed.

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

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

Schema description coverage is 100% and each of the three parameters is documented in-schema, so the baseline is 3. The description reinforces the platform parameter's meaning ('starting with one platform') but adds nothing about name or bundle_id beyond the schema.

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

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

The description gives a specific verb+resource (create a new app in the organization) and immediately scopes it: the app starts with a single platform. It explicitly distinguishes itself from the sibling add_platform, which handles subsequent platforms, so an agent can route between them without opening either schema.

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

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

It names the alternative for the adjacent case ('add the others with add_platform') and states the 'Owners only' precondition, which tells the agent when the call is even permitted. It does not spell out when to prefer create_app over update_app or list_apps, but creation is unambiguous enough that this is a minor gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context that one person may correspond to several users (a logout starts a new one), which primes the agent for multiple results. Beyond that it discloses little about behavior.

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

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

The description is short but front-loads a convoluted, parenthetical-heavy sentence before reaching the useful comparison in the final clause. Some of the conceptual framing earns its place, but the phrasing is harder to parse than necessary.

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?

An output schema exists, so return values need not be explained, and the description does convey the conceptual model and the sibling distinction. For a 2-param read tool this is minimally adequate, though the routing logic could be clearer.

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 are documented in the schema (including the DevReply.login reference and the optional app_id). The description restates the login_id concept but adds no syntax or format detail beyond the schema, 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 names a specific verb (find) and resource (users) and adds a distinctive concept (mapping the app's own login id to DevReply users). However, the core purpose is buried in dense parenthetical prose, and the title ('Find users by the app's id') is slightly misleading since the key input is login_id, not app_id. It does distinguish itself from get_user in the final sentence.

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 last sentence contrasts this tool with get_user ('get_user lists the users linked to one'), which implicitly signals when to use each. But there is no explicit when-to-use/when-not-to-use statement or clear routing guidance; the distinction is left for the agent to 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 and openWorldHint=false, so the safety profile is covered and the description correctly implies a pure read. It adds a sense of the breadth of returned data (installs, push setup, agent reply mode), but says nothing about permissions, staleness, or error behavior, so it is adequate rather than rich.

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 sentence with the resource front-loaded before the field enumeration; every clause carries information. The trailing list is long but each item is a distinct returned attribute, so it earns its space.

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

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

With an output schema present, the description need not explain return values, and the safety profile is carried by annotations. The only real gap is the absence of any routing guidance relative to list_apps/update_app, which keeps it short of 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% and the app_id description already explains the uuid format and the 'from list_apps / optional when only one' semantics. The description adds nothing about parameters, so baseline 3 applies.

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

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

The opening 'One app:' states the resource and implicitly contrasts with the sibling list_apps by specifying a single app rather than a collection, and the field inventory (platforms, public keys, bundle ids, installs, conversations, reply time, push setup, agent reply mode) makes the returned scope concrete. It does not name any sibling explicitly, so it falls short of full differentiation.

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

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

There is no statement of when to call this versus list_apps or get_user, no mention that app_id is optional when only one app exists, and no prerequisites. The only hint is the implied singular-vs-list contrast in 'One app:'.

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?

Rich disclosure beyond the readOnlyHint/openWorldHint annotations: messages are oldest-first capped at the last 200, internal notes and drafts are included, attachment links expire in an hour, user messages are untrusted, and reading does not mark anything as read. These are exactly the behavioral caveats an agent 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?

A single dense sentence, front-loaded with what the tool returns and followed by caveats. Every clause carries information, though the packed parentheticals slightly reduce scannability.

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?

An output schema already covers return structure, yet the description usefully augments it with the last-200 limit, link expiry, and the untrusted/read-state caveats. Coverage is strong, with only sibling routing guidance missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no syntax or format detail beyond the schema for the conversation_id.

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 (read one conversation) and enumerates exactly what it returns: messages oldest-first, internal notes, waiting reply drafts, device, and attachment links. It clearly differs from a bare list tool, but it never names a sibling to contrast with, so sibling differentiation is left implicit.

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

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

The description gives no when-to-use guidance or alternatives. It doesn't tell the agent when to prefer this over list_conversations or watch_conversation, nor any prerequisites beyond the id source noted only in the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the guide includes public keys and is meant to be followed in the repo, but says nothing about the optional app_id behavior when multiple apps exist or about rate/availability 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, no filler, with the core deliverable and platform scope front-loaded. 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 single-parameter tool with an output schema, the description covers what the guide contains and where to apply it. It is nearly complete, missing only guidance on the multi-app case, which the schema already handles.

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 (app_id, optional when only one app) is fully documented in the schema. The description adds no parameter-level 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 deliverable (a step-by-step integration guide) and enumerates the supported platforms (iOS, Android, React Native, Flutter, web), so the agent knows exactly what it returns. It is clear on its own but does not explicitly differentiate itself from setup-adjacent siblings like add_platform or set_ios_push_key.

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?

'Follow it in the app's repository' gives loose operational context, but there is no explicit when-to-use, no prerequisites, and no mention of alternatives (e.g. per-platform setup tools among the siblings). Usage is implied rather than stated.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds something annotations cannot: an explicit warning that name, email, and app-set attributes are untrusted data, which is substantive for how an agent should treat the payload. It stops short of covering error behavior or permission requirements.

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

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

It is a single sentence, so there is no bloat, but the sentence is a dense field inventory whose second half duplicates work an output schema already does. Front-loading the untrusted-data caveat ahead of the field list would have made the priority clearer.

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 an output schema present, enumerating return fields is optional, and the description is adequate for a one-parameter read. However it never says when to prefer this over find_users, nor how failures surface, leaving gaps an agent calling this in a multi-tool workflow could hit.

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 user_id property is fully documented in-schema (UUID format plus sources). The description never mentions the identifier, so it adds nothing beyond the schema — the baseline 3 for a fully documented parameter set 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 enumerates what a user record contains (name, email, attributes, devices, timestamps, conversations), which implies a lookup, but never states the action outright — the verb lives only in the title. More importantly, it does not distinguish this from the sibling find_users, so an agent must infer the difference between searching and fetching by id.

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 at all: no statement that this is the by-id lookup and find_users/list_conversations are the discovery paths, and no mention of what happens if the id is unknown. The schema hints at provenance ('from find_users') but the description itself supplies no routing logic.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: a secret key sees only its one app, and the response includes conversation queue counts and whether agents may reply. Rate limits and pagination are not mentioned, but the credential-scoping detail is valuable.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently packs the resource, credential behavior, and returned fields into one compact statement.

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

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

For a zero-parameter list tool with an output schema and read-only annotations, the description covers the resource, credential-dependent visibility, and key returned fields. Usage guidance and pagination details are missing, but the output schema and annotations fill most other gaps.

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?

There are zero parameters, so the baseline is 4 per the scoring rules. The description correctly does not introduce any parameter details, and the empty schema is fully documented.

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

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

The description identifies the resource (the organization's apps) and its scope, including the credential-dependent visibility rule for secret keys. It does not explicitly state the verb 'list' in the description text (though the title does), and it does not name a sibling like get_app to differentiate use cases.

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 is provided on when to use this tool versus alternatives such as get_app or create_app. The description only states what is returned, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral content beyond that: default sort order, default status, the before/next_before paging contract, and a security caveat that last messages are untrusted user content. That last point is a genuinely useful disclosure, though return shape and rate limits are 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?

Front-loaded with the resource and sort/default, then filters, then paging, then the safety note. Dense and mostly waste-free, but the long filter enumeration substantially restates the schema properties, so it is slightly more verbose than needed.

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 12-parameter list tool with 100% schema coverage and an output schema, this covers everything an agent needs: default scoping, ordering, all filter categories, pagination mechanics, and the untrusted-content warning. No material gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, including the context and attribute object shapes. The description reframes the filters by intent (context = what the app passed when opening the chat; attributes = groups like plan), which adds modest orientation but no syntax or format detail beyond the schema.

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

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

States the resource and scope precisely: conversations sorted newest-activity-first, with open ones defined as the inbox. Combined with the filter enumeration, an agent can tell this apart from get_conversation (single item) and find_users (people lookup) without opening schemas.

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?

Explains the default (open = the inbox) and the full set of filtering dimensions and paging flow, which gives clear context for when to reach for this tool. It never explicitly names an alternative (e.g. get_conversation) or states exclusion conditions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful output behavior—per-tag counts of all conversations and open conversations—but does not discuss pagination, auth, or result shape beyond what the output schema likely 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?

The description is a single efficient sentence, front-loading the resource and the most important returned counts. It is slightly noun-phrase rather than verb-led, but there is no wasted text.

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 low-complexity read tool with annotations and an output schema, the description gives enough context about what is returned. The main gap is usage guidance, which is not strictly required for an agent that already has the schema and annotations.

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 sole app_id parameter is documented in the schema with its source and optional fallback. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states the specific resource (tags on an app's conversations) and the returned detail (total and open conversation counts). It is clearly a read-only listing rather than the tag_conversation mutation, though it does not explicitly name that sibling for contrast.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as tag_conversation or list_conversations. The agent must infer usage from the name and sibling 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?

Annotations only say this is a non-read-only, non-destructive write; the description carries far more: mode semantics tied to an app setting, delivery channels (in-app, push, email if unread), the last-message precondition, and voice/formatting constraints. It fully discloses the behavioral surface an agent needs, with no contradiction of the 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?

Dense but front-loaded: the mode behavior that governs invocation (draft/send/off, last-message rule) comes first, with style rules trailing. The formatting inventory is long, but each item is actionable instruction rather than 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 mutation tool with an output schema, the description covers the mode-conditional behavior, the gating precondition, delivery behavior, and content conventions — everything needed to call it correctly. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that `text` is chat-style Markdown with concrete conventions (bold for the single key action, numbered lists for steps, backticks for exact values) and that with options the text should be the question. This exceeds the schema's generic Markdown note.

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 ('Answers the user') and immediately qualifies it with the three mode-dependent behaviors (draft/send/off), so an agent knows exactly what the call does. It also names get_app as the dependency that determines which mode is active, distinguishing it from generic write siblings like add_note.

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

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

Gives explicit when/when-not conditions: 'send' only works 'when the user's message is the last one', and 'off' refuses outright. What is missing is an explicit alternative (e.g. add_note / send_feedback) for cases where replying is not the right action, but the conditional gating is unusually clear.

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 declare the safety profile (non-destructive, non-idempotent write), and the description goes beyond them: it reveals the human audience ('we read every one'), the downstream effect (it builds the backlog), and a hard privacy constraint (no secrets, no end-user personal data). It omits rate limits, response expectations, or whether a ticket is filed, so it stops short of full transparency.

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

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

Front-loads the purpose before the persuasion and the safety note is well placed at the end. It is slightly padded, though — 'Please do: we read every one and build the backlog from it; complaints and requests are exactly what we want' is encouragement rather than specification and could be halved without loss.

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?

An output schema exists, so return values need no explanation, and all 13 inputs are documented. The description covers purpose, required narrative fields and privacy constraints; the only gap is that it does not say whether feedback receives a reply or is fire-and-forget.

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 every one of the 13 parameters carries a description, so the schema already carries the load. The description's walk-through of why/use case/outcome/workaround/proposal largely restates those schema descriptions rather than adding new semantics, 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 (tell) and a precisely scoped resource: feedback about DevReply itself — 'the SDKs, the setup guide, the dashboard, these MCP tools.' This scope cleanly separates it from app-facing siblings like reply_to_user or add_note, which operate on end users rather than the product team.

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

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

Gives clear context for when to use it ('missing, broken, confusing or good') and an explicit structural rule ('One topic per call, with the reasoning'), plus an exclusion via the secret/personal-data prohibition. It never names a sibling alternative such as reply_to_user, so routing is implied rather than stated.

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

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

Adds behavior beyond the annotations: the credential is 'Stored encrypted, never shown again' (a write-only secret an agent must not expect to read back) and the call requires owner-level auth. That is real context on top of readOnlyHint=false and idempotentHint=true, though re-upload/overwrite semantics are left to the idempotency annotation.

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

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

Three tight sentences, front-loaded with the action and effect, then the security/store constraint, then the auth and acquisition steps. The console navigation path is slightly list-like but it is genuinely actionable information rather than 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?

An output schema exists so return values need no explanation, and the schema fully documents both parameters including the optional single-app case for app_id. Auth requirements, secrecy of the stored key, and where the credential originates are all covered, leaving nothing an agent needs before calling it.

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 already 100%, so baseline is 3. The description still adds meaning by explaining what the service_account string actually is and how to obtain it (Firebase console → Project settings → Service accounts → Generate new private key), which the schema's 'as text' wording does not convey.

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 (uploads) and resource (the app's Firebase service account), plus the outcome (Android users get pushes for replies via FCM). It is clearly distinguishable from the sibling set_ios_push_key and from set_app_icon/update_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?

Gives explicit prerequisites and timing: 'Owners only' and 'The person creates it once,' with a step-by-step pointer to where the key comes from in the Firebase console. It does not name set_ios_push_key as the alternative for iOS devices, which is the one routing cue an agent might still want.

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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description layers on non-obvious behavior the annotations cannot express: accepted formats, a 6 MB cap, server-side square cropping and 512 px resizing, and where the icon surfaces (chat header, emails, dashboard). That is exactly the extra context an agent needs before committing an upload.

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

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

A single dense paragraph that front-loads the verb, then the payload constraints, then the effect and permission requirement. Every clause carries information; no filler sentences.

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?

An output schema exists, so return values need not be described. Between the annotations (idempotent, non-destructive writes), the schema, and the description's format/size/processing/permission details, an agent has everything required to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'Base64 of the image file' by enumerating accepted formats (PNG, JPEG, WebP, GIF) and the 6 MB limit, plus guidance on the ideal source image. It adds real semantic value, though it doesn't discuss the app_id fallback beyond what the schema already states.

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

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

States a specific verb and resource ('Uploads the app's icon') that is unmistakable and clearly distinct from siblings like set_android_push_key, set_ios_push_key, and update_app. The agent knows exactly what this does without inspecting the schema.

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

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

Gives a clear access precondition ('Owners only') and a recommended source ('the app's own 1024 px icon from the repository is ideal'), which tells the agent when invocation will succeed. It stops short of naming alternatives or saying when not to use this tool (e.g., versus update_app).

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 non-destructive, idempotent, closed-world writes. The description adds a genuine behavioral fact not in the structured data: the categorization is internal and 'the user doesn't see it.' It doesn't say whether re-setting replaces a prior category, but the idempotentHint covers repeated calls.

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 terse sentences; the core action is front-loaded and the visibility caveat is a single useful clause. 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 2-parameter required-field tool with an output schema, the description covers purpose and the key invisible-to-user behavior. It omits routing guidance relative to tag_conversation/set_status and overwrite semantics, but those are minor given full schema coverage.

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

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

Schema coverage is 100%, with both parameters fully described and the category enum spelled out in both schema and description. The description adds no syntax or format meaning beyond restating the enum, so baseline 3 applies.

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

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

States a specific verb ('Files') plus resource ('a conversation') and enumerates the exact category enum values, so the agent knows precisely what the tool does. It is distinguishable from siblings like set_status and tag_conversation, though it never explicitly contrasts itself with 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?

The description says nothing about when to use this versus tag_conversation or set_status, nor any preconditions (e.g., that the conversation must exist or have no category). Usage is only implied by the verb.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false). The description adds meaningful behavioral context beyond them: the key is stored encrypted, it is never shown again after upload, the operation requires owner privileges, and the credential must be sourced out-of-band from Apple. The only missing piece is whether re-uploading replaces an existing key, though idempotentHint implies it.

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

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

Three tight sentences, each earning its place: what is uploaded, how it is stored and its one-time visibility, who may call it, and why the caller must obtain the key externally. No redundancy with the title or schema.

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?

An output schema exists, so return values need not be explained. For a credential-upload mutation the description covers authorization (owners only), security handling (encrypted, never shown again), and the external prerequisite (Apple has no creation API) — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so every parameter including the optional app_id is already documented in the schema. The description restates the payload components but adds no format, validation, or edge-case detail beyond what the schema provides. Baseline 3 applies 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 (uploads) and resource (the app's APNs key), enumerating exactly what the payload contains (.p8 contents, Key ID, Team ID, bundle ID). It is trivially distinguishable from the sibling set_android_push_key, and the purpose (delivering push notifications for replies) is stated 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?

Gives a clear precondition — 'Owners only' — and contextualizes the workflow by noting Apple provides no API to create the key so the user must download it first. It does not explicitly contrast with set_android_push_key, but the iOS scope makes the alternative obvious from the name.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false. The description adds genuinely new behavioral context: the action is user-visible ('Marked as resolved'), may trigger a push notification, and removes the conversation from the open inbox.

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, effect stated first, then user-visible consequence, then the caution. 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?

An output schema exists, so return values needn't be described. Both parameters are covered by the schema, and the description supplies the side-effect and cautionary context an agent needs before mutating a conversation's status.

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 enum values are already documented in the schema, so the description merely restates the resolved/open meaning. Baseline 3 applies since the schema does the heavy lifting for both 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?

Specific verb (resolve/reopen) plus resource (conversation) and a clarifying effect ('it leaves the open inbox'). This cleanly separates it from sibling mutation tools like set_category, tag_conversation, or reply_to_user.

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

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

Gives explicit when-to-use guidance ('Only resolve when the team has actually answered') and explains the two states. It does not name a sibling alternative or state when reopening is appropriate, so it stops short of full routing guidance.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds meaningful context beyond that: tags are invisible to the end user, constrained to lowercase letters/digits/_-:. up to 32 chars, and capped at 10 per conversation.

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

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

A single dense paragraph that front-loads the core action, then constraints, then navigation to sibling tools. No filler, though the character-class and length rules are duplicated from the schema, which is slightly redundant.

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 a full output schema, return values need no explanation. The description covers purpose, scope, format limits, visibility semantics, and the two relevant sibling tools, leaving nothing an agent needs missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents add, remove, and conversation_id with examples and format rules. The description largely restates those constraints (character set, length, count), which is helpful reinforcement but adds little beyond the structured fields; 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?

The description opens with a specific verb pair and resource ('Adds or removes tags on a conversation') and immediately scopes the concept as team-internal tags the user never sees. An agent can distinguish this from siblings like add_note or set_category 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?

It explicitly routes to alternatives: filter with list_conversations(tag) and enumerate with list_tags. It gives clear context but no explicit 'do not use this for X' exclusion, so it falls just short of a 5.

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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the safety bar is lower. The description adds genuinely useful context beyond the annotations: the Owners-only authorization requirement and the fact that agent reply mode is out of scope here. It does not describe partial-update semantics or overwrite behavior.

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

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

The text is compact and free of padding, but it is not front-loaded: it opens with a noun fragment and parenthetical examples instead of a purpose statement, forcing the reader to assemble the action from the name and title. Three short sentences, each carrying content, but the structure is weak.

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?

An output schema exists, so return values need not be explained, and the schema covers both field semantics and the 'only those given change' / 'empty removes one' behavior. What the description uniquely contributes — owner permission and the reply-mode exclusion — is helpful, but it omits any statement of the operation itself for a six-parameter, nested-object mutation.

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

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

Schema coverage is 100%, so the baseline is 3. The description largely restates fields the schema already documents in detail (links, bundle_ids, reply_within, app_id), adding no syntax, format, or interaction meaning beyond what the structured data 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?

The description enumerates the app attributes that can be changed (bundle ids, package name, site domain, promised reply time, store pages) but never states the action in a verb phrase; it reads as a fragment list rather than 'updates the app'. A reader must infer 'update' from the tool name and title. The scope is discernible, so it is not tautological, but the purpose is only implied.

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

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

It supplies a real prerequisite ('Owners only') and a clear exclusion ('Agent reply mode is set by a person in the dashboard'), which tells the agent one thing this tool cannot do. However, it names no alternative sibling (create_app, get_app, list_apps) or conditions for choosing between them. Usage is implied rather than guided.

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 say readOnlyHint/openWorldHint; the description adds substantial behavior beyond them: SSE `data:` lines shaped like get_conversation messages, `: ping` keep-alives every 30s, automatic reconnect/resume, and termination on resolution (`end` event) or after 24h. This is exactly the operational context an agent needs to run a background stream safely.

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?

Well front-loaded: the core purpose (stream new messages via an SSE URL) leads, followed by execution details. It is a dense single paragraph rather than over-long, and each clause carries real information, though it could be broken into shorter sentences for scanability.

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?

Given the streaming/background-execution complexity, the description covers how to run it, message format, keep-alives, reconnection, and termination. Even though an output schema exists, the added lifecycle detail is appropriate, and nothing needed to invoke it correctly is missing.

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

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

With one parameter at 100% schema description coverage, the schema already documents `conversation_id` and its source (list_conversations/get_user). The description adds no additional parameter syntax or constraints, 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+resource (watch/stream new messages in a conversation) and precisely what it returns: a URL that streams messages plus a `command` to run. It implicitly distinguishes itself from the re-reading siblings by framing itself as an alternative to re-reading the conversation.

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

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

Gives a clear when-to-use condition: 'Use it while you're actively working a conversation with the user,' and contrasts with re-reading, which points to get_conversation. It does not explicitly name get_conversation as the alternative or state when not to use it (e.g. for one-off history reads), so it stops short of a full 5.

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