Missive MCP by usefulapi

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

Annotations provide only a title and destructiveHint=true, so the description carries most of the behavioral burden. It says nothing about authentication requirements, how duplicate contacts are handled, whether the call is idempotent, or what side effects occur on failure.

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 scope; the endpoint reference is modestly useful for agents mapping to the HTTP API. Nothing is redundant or padded, though 'Missive: POST /contacts' is of marginal value.

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 full schema coverage and only one required parameter, the mechanics of the call are covered. However, with no output schema the description should ideally indicate what is returned (e.g. the created contact id) and what errors look like when the contact book is invalid, which it omits.

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 (infos, starred, first_name, last_name, memberships, contact_book) is already documented in the schema. The description adds only the fact that contact_book is mandatory, which the schema's required list already states. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a contact') plus the scoping constraint ('in the given contact book'), and the endpoint reference (POST /contacts) confirms the operation. It is clearly distinguishable from the read-oriented siblings (missive_get_contact, missive_list_contacts), though it doesn't explicitly name them as alternatives.

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

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

No when-to-use or when-not-to-use guidance, and no alternative named. The requirement that a contact book id be obtained first (e.g. via missive_list_contact_books) is only implied by 'in the given contact book', so the agent must infer the prerequisite.

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

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

Annotations carry only destructiveHint=true; the description adds the concrete reason — send=true dispatches a real email immediately and send_at schedules it — which is exactly the behavioral disclosure an agent needs to avoid an accidental send. It omits auth/permission requirements and what is returned, so not a full 5.

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

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

Three tight sentences with the highest-risk information (the send warning) front-loaded, followed by threading guidance and the API endpoint. 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 13-param mutation tool with no output schema, the description covers the critical destructive behavior and threading; the remaining parameter detail is fully carried by the schema. Minor gaps around required sender/organization prerequisites and the returned draft identifier keep it from 5.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the send/send_at warnings and the conversation threading field. The description largely restates that, adding no format or syntax detail beyond it; baseline 3 applies.

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

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

States a specific verb and resource ('Create a draft email/message') and immediately clarifies the scope distinction that matters most: draft-save versus actually sending. An agent can tell this apart from the list_* siblings at a glance.

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 actionable context: use `conversation` to attach to an existing thread, and use send/send_at only when you intend a real send. It stops short of naming alternatives or stating when-not to use it (e.g., replying vs new draft), but the conditional guidance is 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds only the REST mapping (GET /contacts/{id}), which is marginal; it says nothing about error behavior (e.g. not-found) or response shape.

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

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

Two short sentences, front-loaded with the action and resource. The endpoint restatement is arguably redundant with the tool name, keeping it just below 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 read-only getter with full schema coverage, the core need is met, but with no output schema the description could have sketched what a contact object contains or how a missing id is handled. Adequate but with clear 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?

Schema description coverage is 100% and the single 'id' parameter is fully documented in the schema (UUID-like string). The description's 'by id' phrase adds no syntax or format detail beyond the schema, 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 ('Get') and singular resource ('a single contact by id'), which implicitly distinguishes it from the plural missive_list_contacts sibling. It does not explicitly name or contrast with that sibling, so it falls short of a 5.

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

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

There is no guidance on when to use this versus missive_list_contacts or missive_get_conversation; usage is only implied by the tool name. No prerequisites, exclusions, or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the REST endpoint mapping (GET /conversations/{id}), which gives no new behavioral context such as error behavior for invalid/missing ids or the shape of the returned 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?

Two short sentences, front-loaded with the actual purpose; the endpoint mapping is slightly redundant but compact. Nothing is padded.

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

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

For a one-parameter read tool with readOnlyHint and full schema coverage, the essentials are present. However, there is no output schema, so the description could have briefly indicated what a fetched conversation contains and how it differs from list results; that gap keeps it at minimum-viable.

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

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

Schema description coverage is 100% and the single parameter is already documented as a UUID-like resource id. "by id" in the description adds nothing beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource: "Get a single conversation by id" clearly states the operation and singular scope, implicitly distinguishing it from missive_list_conversations. It stops short of naming or contrasting with siblings like missive_get_message or missive_list_conversation_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?

No when-to-use guidance, no exclusions, no pointer to alternatives for fetching related resources (messages, drafts, comments). The agent must infer that this is the single-item counterpart of missive_list_conversations.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description usefully adds that the full message body is returned (as opposed to a truncated listing), but says nothing about pagination, error cases, or what happens with an invalid id/conversation pairing.

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 delivers the core capability, followed by a short API reference. Nothing is padded, though the raw endpoint string is of marginal value to an agent that already has the parameters.

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 it partially does so by noting the full body is included. However, it does not describe the message object's structure or fields, leaving the agent to discover the response shape at call time.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds only the REST path mapping ('GET /conversations/{conversation_id}/messages/{id}'), which corroborates but does not extend the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Get a single message, including the full body') and implies the single-vs-list distinction against missive_list_conversation_messages. It does not name the sibling explicitly, so the differentiation is left to inference.

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 the many list/get siblings, nor any stated prerequisites or exclusions. The only usage signal is the implicit sense of fetching one message rather than many.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered; the description adds the backing endpoint (GET /contact_books), which corroborates a non-mutating read. It does not disclose return format or pagination behavior beyond what the schema implies, so with annotations the bar is met at a 3.

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 clauses, front-loaded with the verb and resource, with the endpoint reference appended. Every token earns its place; 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 simple zero-required-param read-only list tool with full schema coverage and no output schema, the description covers what is needed to invoke it correctly. Only minor gaps remain around ordering/return shape, which the schema partially implies.

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 (limit, offset) are fully documented in the schema including defaults and max. The description adds nothing on 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?

States a clear verb+resource ('List contact books') and parenthetically disambiguates it as address books, which helps separate it from sibling list_contacts and list_contact_groups. It does not explicitly contrast those siblings, so it stays short of a 5.

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

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

No guidance on when to use this tool versus the many sibling list tools, and no stated prerequisites or exclusions. The only hint is the resource name itself.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the raw endpoint string "GET /contact_groups" and nothing about pagination defaults, ordering, or result size, so it contributes essentially no behavioral context beyond 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?

Two short sentences with the purpose front-loaded and no filler. The trailing "Missive: GET /contact_groups" is mildly redundant with the purpose sentence but cheap and arguably useful for API mapping.

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

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

For a simple paginated list tool with a fully documented schema and readOnly annotations, the core information is present. The gaps are the undefined relation to missive_list_organizations and the absence of any output-shape hint (no output schema exists), which leaves the agent to infer the return structure.

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 four parameters (kind, limit, offset, contact_book) are already documented, including the kind enum. The description's phrase "within a contact book" loosely reinforces the contact_book scoping but adds no format or behavioral detail beyond the schema, matching the baseline for high coverage.

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

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

States a specific verb (List) and resource (contact groups/organizations) scoped to a contact book, plus the underlying endpoint. However, the sibling tool missive_list_organizations overlaps with the kind="organization" mode here, and the description never distinguishes the two, so an agent cannot fully disambiguate from the name and text alone.

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

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

The description gives no context on when to use this tool rather than missive_list_organizations, missive_list_contact_books, or missive_list_contacts, all of which are close siblings. No prerequisites or pagination guidance are provided.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds no behavioral context beyond restating that it is a GET /contacts call — nothing about pagination behavior, default result size, or how deleted/modified filters affect output. It does not contradict the annotations, but it contributes almost nothing.

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 clauses, purpose front-loaded with no filler. The 'Missive: GET /contacts' tail is marginal value (API mapping) but 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?

For a 7-parameter read-only list tool with full schema coverage and no output schema, the essentials are covered by structured fields. However, nothing explains the return shape or pagination semantics, and usage context versus sibling list/get tools is absent, so it is only minimally complete.

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

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

Schema description coverage is 100%, so limit, order, offset, search, modified_since, include_deleted, and contact_book are all documented in the schema with defaults and formats. The description adds no param-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List contacts in a contact book'), which is enough to separate it from missive_get_contact and missive_list_contact_books. It does not explicitly name a sibling, but the scope (list, within a book) is unambiguous.

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

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

No guidance on when to choose this over missive_get_contact (single contact), missive_list_contact_books, or missive_list_contact_groups. The only context offered is the endpoint mapping and the implied scoping to a contact book, which is already implied by the required parameter.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully clarifies that these are internal team-chat comments (not external/client-visible content) and maps to GET /conversations/{id}/comments, but it omits ordering, pagination, or rate-limit behavior for a list endpoint.

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

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

Two sentences, zero filler, and the core purpose plus the disambiguating '(team chat)' qualifier are front-loaded before the endpoint reference.

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

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

For a simple read-only lister with full schema coverage this is close to sufficient, but with no output schema the description should have sketched the return shape (author, timestamp, body) or the pagination contract implied by the until cursor. Adequate but leaves real 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?

Schema description coverage is 100%, so id, limit, and until are already documented in the schema, giving a baseline of 3. The description adds no extra parameter meaning (e.g., cursor semantics or default limits) beyond the endpoint path implying 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 (list) and resource (internal comments/team chat on a conversation), and the parenthetical distinguishes the payload from the sibling message/post/draft listers. It does not name a sibling tool explicitly, so it falls 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?

The description says what the tool returns but never states when to reach for it versus missive_list_conversation_messages, _posts, or _drafts. Usage is only implied by the tool name; no prerequisites or exclusions are given.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description does not need to restate safety. It adds the endpoint mapping but says nothing about pagination behavior, ordering of drafts, or whether drafts from other users 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?

Two short sentences with the operation front-loaded and no wasted prose. The endpoint citation is marginally redundant given the tool name but is compact and useful for disambiguation.

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

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

A simple read-only list endpoint with full schema coverage and no output schema, so the description does not need to explain return values. Only the absence of any when-to-use framing and any note on draft ordering/paging limits keeps it from being fully complete.

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

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

Schema description coverage is 100%, so id, limit, and until are already documented in the schema, including the cursor semantics of 'until'. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline-3 case.

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

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

States a specific verb+resource ('List draft messages on a conversation') and appends the underlying endpoint, which pins down exactly what is returned. It is naturally distinct from the sibling list tools (messages, comments, posts), though it never names an alternative explicitly.

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

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

There is no guidance on when to call this versus missive_list_conversation_messages, missive_list_conversation_comments, or missive_create_draft. The agent must infer usage purely from the resource noun.

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

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

Annotations already declare readOnlyHint=true, so the description need not restate safety. Beyond that, it adds no behavioral context — no pagination behavior, no statement about ordering (newest/oldest), and no note that the fixed max of 10 caps results despite the schema exposing limit and until cursors.

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 very short sentences with the purpose front-loaded and no padding. The trailing API-endpoint line adds little value but costs almost nothing in length.

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

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

For a simple read-only list tool with full schema coverage, the description covers the core purpose adequately. However, with no output schema it says nothing about the shape or ordering of returned messages, and the notably low 'max 10' limit constraint is left entirely to the schema.

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

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

Schema description coverage is 100%, so all three parameters (id, limit, until) are already documented in-schema, establishing the baseline of 3. The description contributes no additional meaning about the id format, the until cursor semantics, or the limit cap.

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 messages (emails) in a conversation') and the parenthetical '(emails)' implicitly separates it from sibling collection endpoints like list_conversation_comments, drafts, and posts. It never names a sibling explicitly, so differentiation relies on the agent inferring the distinction.

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

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

There is no guidance on when to use this tool versus alternatives such as missive_get_message, missive_list_conversation_comments, or missive_list_conversations. The only additional line is an API endpoint mapping ('Missive: GET /conversations/{id}/messages'), which restates the operation rather than advising usage.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description corroborates this by naming the read endpoint (GET /conversations/{id}/posts) and notes the items are integration/app-generated, but adds nothing about pagination ordering, result size behavior, or auth scopes.

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

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

Two short sentences, with the purpose front-loaded ahead of the endpoint reference. Efficient, though the trailing 'Missive: GET /conversations/{id}/posts.' restates metadata that adds little for tool selection.

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

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

For a simple read-only list tool whose schema fully documents its three params, the description is adequate but thin: with no output schema, it does not describe the shape or contents of returned posts, nor how the cursor pagination behaves.

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%: id, limit, and the until cursor are all documented in the schema. The description adds no parameter meaning 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?

States a specific verb (List) and resource (posts on a conversation), and the parenthetical '(integration/app-generated items)' clarifies what a 'post' is, distinguishing it conceptually from conversation messages, comments, and drafts. It does not explicitly name those siblings, so the differentiation relies on the reader's inference.

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

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

There is no guidance on when to use this rather than the sibling listers (conversation_messages, conversation_comments, conversation_drafts). Usage is only implied by the tool name; no exclusions or prerequisites are given.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is incremental. It adds the exclusivity constraint on the filter set, but says nothing about default page size, pagination behavior beyond what 'until' implies, or what a response contains. Useful but partial against a lowered bar.

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 resource, then the critical constraint, then a short note. Three compact clauses with no padding, though the bare 'Missive: GET /conversations' adds little for an agent that already has the tool.

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 15-parameter, no-output-schema read tool, the description covers the one non-obvious failure mode (filter exclusivity) while the schema carries defaults and per-parameter meaning and annotations carry the safety profile. Return shape is unspecified but that is a minor omission for a list endpoint.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, making 3 the baseline. The description does add one genuinely schema-absent rule — that exactly one mailbox-type filter must be supplied — which raises the value, but it leaves limit, until, and the two contact/organization filters unaddressed.

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

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

States a specific verb and resource ('List conversations (email/chat threads)') and extends scope with the HTTP endpoint. It is clearly separable from read-oriented siblings like missive_get_conversation and message-level tools, though it does not explicitly name any alternative.

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 strong invocation rule — EXACTLY ONE mailbox-type filter out of an enumerated set — which is exactly the kind of guidance an agent needs to avoid invalid calls. It stops short of saying when to prefer this over siblings such as missive_list_conversation_messages or missive_get_conversation.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful scope constraint that only organizations the caller belongs to are returned, but says nothing about pagination defaults, result ordering, or empty-result behavior.

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

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

Two short sentences with the purpose front-loaded; nothing is padded. The trailing "Missive: GET /organizations" restates the endpoint and adds little, but it is not harmful.

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

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

For a simple read-only list tool with a fully documented two-parameter schema and no output schema, the description says enough to invoke it correctly. Only pagination behavior and result shape are unaddressed, which the annotations and schema largely neutralize.

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 limit and offset are already documented in the schema. The description adds no syntax, default values, or pagination semantics beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (organizations) and adds the scoping qualifier "you belong to." This clearly separates it from sibling list tools such as missive_list_users or missive_list_teams, though it never names a sibling explicitly.

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

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

No indication of when to use this tool versus the other list tools, and no prerequisites or exclusions are given. The only contextual clue is the tool name itself; the description offers no 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 readOnlyHint=true, so the safety profile is covered. The description adds only the raw API endpoint reference, disclosing nothing about pagination behavior, filtering semantics, or what a 'canned response / template' object contains.

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

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

Two terse sentences with no filler, front-loading the purpose before the endpoint reference. Efficient, though the endpoint note arguably earns little 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 no output schema and no annotations beyond read-only, the description is barely adequate: it says nothing about pagination defaults, the shape of results, or how organization filtering interacts with listing. A list tool with three optional params deserves a bit more context.

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 limit, offset, and organization all documented in the schema itself. The description adds no additional parameter 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 and resource: 'List canned responses / templates.' An agent can identify what it returns, though it does not explicitly distinguish itself from siblings like missive_list_conversation_drafts or missive_list_shared_labels, which are the closest conceptual neighbors.

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 indication of when to use this tool versus alternatives, nor any prerequisite or exclusion. The only usage signal is the implied 'GET /responses' mapping, which does not help an agent decide between the many list_* siblings.

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 the description only restates read-only behavior via 'GET /shared_labels'. It adds no context on pagination limits, rate limits, ordering, or what the returned labels contain. The endpoint mapping is the only marginal addition beyond annotations.

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

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

Two short sentences, nothing redundant, with the core action front-loaded and the supporting API detail trailing. Every element 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-required-param, read-only list tool with 100% schema description coverage and no output schema, the description is nearly sufficient. The main omission is any note on pagination behavior or result shape, but the schema carries most of that burden.

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?

All three parameters (limit, offset, organization) are fully documented in the schema, so the baseline is 3. The description adds nothing about parameter semantics — no explanation of pagination defaults or organization filtering behavior 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 ('List shared labels') and clarifies the ambiguous term with a parenthetical ('team-shared folders/tags'), plus the backing API call. No sibling in the list overlaps with labels, so explicit differentiation isn't required, but it also doesn't position itself against nearby list tools.

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

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

There is no when-to-use guidance, no prerequisite (e.g., auth/organization scoping), and no mention of alternatives such as other list endpoints. The verb 'list' implies retrieval, but nothing tells the agent under what circumstances to pick this tool.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the annotation carries the safety profile. Beyond that the description only adds the API endpoint mapping ('Missive: GET /teams'), which is not behavioral context an agent needs, and it says nothing about pagination behavior, result scope across multiple organizations, or empty-result handling.

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

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

Two short sentences with the core purpose front-loaded and no filler. The trailing 'Missive: GET /teams' line is endpoint metadata that does little for tool selection but is harmless and cheap.

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

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

For a simple read-only list tool with full schema coverage and a readOnly annotation, the description covers what is needed to call it. The only gap is that it does not hint that this is a paginated collection, which matters slightly when listing.

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 limit, offset, and organization fully documented in the schema itself. The description mentions organizations only incidentally and adds no syntax or filtering guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List teams in the organization(s)'), which lets an agent distinguish it from sibling list tools like list_users or list_organizations. It does not, however, explicitly name or differentiate itself from any sibling tool.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer when looking up people, organizations, or teams. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The only added detail is the underlying endpoint (GET /users), which merely restates read-only behavior rather than adding new context. Pagination behavior, default/max page size, and organizational scoping semantics are not disclosed despite limit and offset parameters.

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 very short sentences with the resource and scope front-loaded. The endpoint note ("Missive: GET /users") is close to filler but is brief and does not dilute the core 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?

There is no output schema, so the description ideally would convey the return shape (user objects, id/name fields) and pagination behavior. For a simple, fully-parameterized read tool it is minimally adequate, but an agent gets no picture of what comes back.

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

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

Schema description coverage is 100%, so all three parameters (limit, offset, organization) are already documented in the schema. The description adds nothing about parameter usage or defaults, so the baseline 3 applies.

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

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

States a specific verb and resource ("List users") and clarifies the resource with "(team members)", which disambiguates it from contacts/contact books. However, it does not distinguish it from the closest sibling, missive_list_teams, leaving the users-vs-teams boundary to inference.

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

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

No when-to-use guidance, no prerequisite or exclusion notes, and no mention of alternatives among the many list_* siblings. Nothing tells an agent when listing users is the right call versus listing teams or organizations.

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?

destructiveHint=true is already carried by annotations, and the description usefully discloses the destructive sub-operations (unassign users, remove labels, close/archive) plus the underlying PATCH endpoint. It does not, however, explain whether unspecified fields are left unchanged, whether operations are idempotent, or what authorization is needed for a mutating call.

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-loads the operation list, followed by a short API mapping. Efficient overall, though the 'Missive: PATCH /conversations/{id}' fragment is informational rather than decision-relevant for tool selection.

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 mutation tool with full schema coverage and no output schema, the description adequately frames scope and the destructive operations. It stops short of covering partial-update semantics or auth requirements, which is 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% across all 12 parameters, so the schema already documents id, team, close, reopen, color, subject, assignees, labels, and organization. The description only restates those capabilities in prose, adding no syntax, format, or dependency detail beyond the schema.

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

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

States a specific verb (update) and resource (conversation), then enumerates the exact mutation surface: assign/unassign, labels, close/reopen, inbox, subject/color/team. This immediately separates it from the read-oriented siblings get_conversation and list_conversations without needing the schema.

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

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

The enumerated operations imply when the tool is applicable, but there is no explicit when-to-use/when-not guidance and no mention of prerequisites such as needing an existing conversation id or required permissions. Usage is inferable but never stated.

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