Sakari MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context not in annotations: the effect is state-changing but auto-reversible on the next inbound message, which materially affects whether an agent should hesitate. It stops short of saying what happens when closing an already-closed conversation or what errors to expect.

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 line, front-loaded with the operation class (WRITE) followed by action, effect, and endpoint. Every clause earns its place and 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 mutation with no output schema, the definition covers what changes, the reversibility trait, and the transport. Minor gaps remain on error/idempotent-replay behavior and on the accountId path variable that the schema does not expose, but nothing blocks 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?

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics and baseline 3 applies. The description mentions the conversationId path segment but adds no format, encoding, or lookup guidance beyond it.

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

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

States a specific verb and resource ('mark a conversation closed in the Sakari inbox') with a leading WRITE marker, which cleanly separates it from read-only siblings like sakari_get_conversation and sakari_list_conversations. The endpoint path reinforces exactly what object is mutated.

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

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

Usage is only implied by the parenthetical that a new inbound message reopens the conversation, which hints the close is not permanent. There is no explicit statement of when to close versus when to leave a conversation open, and no named alternative (there is no reopen sibling to route to).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety bar is lower; the description still earns credit by disclosing the duplicate-mobile merge behavior and the important caveat that "a contact is not opted in to messages by this call." It omits permissions/auth requirements and what the call returns, keeping it below a 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 short sentences, front-loaded with the write operation and immediately followed by the riskiest edge case (duplicate mobile merge). 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?

With no output schema, an agent still knows the key semantics: it is a write, duplicate mobiles are merged per merge_strategy, and no opt-in occurs. Missing return-value shape (e.g. created contact id) and auth requirements are the only notable gaps for a 6-param mutation tool.

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

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

Schema description coverage is 50%, so the description should compensate somewhat; it mentions merge_strategy but only restates the enum values ("append, core or remove, per Sakari") without explaining what each mode actually does to the existing contact. email, first_name and last_name get no mention in either place.

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 ("WRITE: create a contact") and adds the duplicate-mobile condition that qualifies the operation. It doesn't name the sibling sakari_update_contact as the alternative for modifying an existing contact, so differentiation is only 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?

"If a contact with the same mobile number exists, merge_strategy decides what happens" gives useful context about when merging applies, and it clarifies this is not an opt-in action. However, there is no explicit when-to-use/when-not guidance and no routing to sakari_update_contact or sakari_get_contact for the modify/check paths.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description usefully reinforces that nothing is sent and names the endpoint, but it does not disclose what happens on duplicate names, name-uniqueness rules, or the non-idempotent behavior beyond the 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?

A single front-loaded line with the write semantics and the key disambiguation first. The trailing endpoint path is the only element of marginal value to an agent selecting 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 simple two-parameter creation tool with a fully documented schema and no output schema, the description covers purpose, side effects, and endpoint. It could note that a template identifier is returned, since no output schema exists to convey that, but otherwise nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% with only two required parameters, and the schema already documents the placeholder syntax for 'text' and the length bounds. The description adds no parameter meaning beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('create a reusable SMS template') and pre-empts the most likely confusion by asserting it does not send anything, which separates it from sibling sakari_send_message. It stops short of naming siblings explicitly, so it lands just under the top mark.

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

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

The 'WRITE' prefix and the negative clarification imply the tool's role, but there is no explicit statement of when to use it versus sakari_list_templates (e.g., to check for duplicates) or when to prefer sending a message instead. Usage is inferable 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned field set and the security-relevant guarantee that API credentials are never returned, which an agent cannot infer from structured fields.

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

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

Two compact sentences, front-loaded with the resource identity and followed by the caveat about credentials. The field enumeration is dense but earns its place because there is no output schema; the trailing endpoint path is mildly redundant but adds specificity.

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 read with no output schema, listing the returned fields plus the credential-exclusion note covers nearly everything an agent needs. Minor gaps remain: nothing about response shape (single object) or whether balance values are live or currency-qualified.

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?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline of 4 applies. The description does not need to compensate for any schema gaps.

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 a specific resource — the Sakari account tied to the presented credentials — and enumerates the fields it returns (name, plan, balance, default country, business info, options). That makes it distinguishable from most siblings, though it does not explicitly state that sakari_get_balance is a narrower variant despite the overlap in the field list.

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

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

Usage is only implied: the description makes clear this is the way to inspect the credential-owning account, but it never says when to prefer it over sakari_get_balance or what conditions select it. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered without description help. The description's added value is the return-field inventory, which partially compensates for the missing output schema, but it says nothing about freshness, caching, or error behavior.

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

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

Two terse fragments with the useful return-field list front-loaded and no filler. The trailing endpoint path is arguably redundant for an agent but does no harm.

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 parameters, no output schema and annotations covering safety, the description needs only to say what comes back, which it does via the field list. It falls short of fully describing the response shape or units for the price/segment values.

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?

The tool takes zero parameters, so the schema baseline is 4 and there is nothing for the description to compensate for. The embedded path mentions an {accountId} that is not exposed in the schema, which is mildly confusing but does not affect invocation.

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 exactly what the call returns (prepaid balance, default country, remaining segments, price per segment), so an agent can infer it retrieves account balance information. The verb is implicit rather than stated, and it never contrasts itself with the closely related sakari_get_account sibling.

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 versus alternatives such as sakari_get_account, which likely also exposes account-level data. The only guidance is the raw endpoint string, which does not help an agent choose between 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, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds the REST endpoint path and the notion of a historical record, but does not discuss return format, errors, or authentication, leaving some behavioral context unstated.

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 two compact sentences with the core retrieval purpose front-loaded. The endpoint path is somewhat implementation-level rather than agent-facing, but it does not bloat the definition significantly.

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 one-parameter read tool with full schema coverage and informative annotations, the description is largely complete. It does not explain the returned fields or not-found behavior, but the core operation is sufficiently clear for 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 coverage is 100% and the single call_id parameter is already documented as 'Sakari call id.' The description reinforces that the lookup is by id but adds no format or semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific resource and retrieval scope: one call history record by id. It implicitly distinguishes itself from the sibling list_calls by specifying a single record, though it does not name the alternative explicitly.

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

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

Usage is implied by 'by id' and the required call_id parameter, but the description does not explicitly say when to use this versus sakari_list_calls or what prerequisites exist. It provides only minimal contextual 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint path and contributes no behavioral context such as error behavior for a missing campaign or account scoping 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?

Two very short sentences with zero waste and the core purpose front-loaded. It is arguably under-specified rather than padded, but structurally it is clean and easy to scan.

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

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

For a single-parameter read tool with full schema coverage and read-only annotations, the essentials are present. However, with no output schema the description gives no hint of what a campaign object contains, leaving the agent to guess at the response shape.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Sakari campaign id', so the schema does the heavy lifting. The description's phrase 'by id' adds nothing 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 (get) and resource (campaign), and 'One campaign by id' signals single-resource retrieval as opposed to the sibling sakari_list_campaigns. It does not name the sibling explicitly, but the singular scope is clear enough to differentiate.

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

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

Usage is only implied: an agent can infer this is for fetching a known campaign id and that list_campaigns is for discovery. There is no explicit when-to-use, no mention of what to do if the id is unknown, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that by previewing the response content (line type, validity, opt-in and blocked state) in the absence of an output schema. It does not mention auth scopes, rate limits, or not-found 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 compact clauses with zero filler; the 'one contact by id' scope and the returned fields are both 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 one-parameter read tool with full annotation coverage, this is nearly complete – the field list substitutes for the missing output schema. Only error/nonexistent-id behavior is 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?

Single parameter with 100% schema description coverage ('Sakari contact id.'), so the schema already carries the semantics. The description only reinforces 'by id' and adds no format, sourcing, or lookup guidance beyond the schema.

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

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

States a specific retrieval action ('One contact by id') and enumerates the concrete fields returned (name, mobile with validity/line type, email, lists, attributes, opt-in/blocked). The singular 'by id' implicitly separates it from sakari_list_contacts, but no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer it should call this when it already has a contact id and use sakari_list_contacts otherwise. There is no explicit when-to-use, prerequisite, or fallback guidance, and no mention of what happens if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying REST endpoint path, with no detail on what the response contains or error behavior for a missing id. With annotations carrying the behavioral load, this is adequate but thin.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the alternative routing. The trailing endpoint path is marginally useful and doesn't bloat the definition.

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 tool with full annotation coverage and a documented single parameter, this is close to sufficient. However, with no output schema, the description gives no hint of what a 'conversation' object contains, leaving the agent to infer the return shape.

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

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

There is a single required parameter with 100% schema description coverage ('Sakari conversation id.'), so the schema does the work. The description's 'by id' adds nothing beyond it, which is the expected baseline when coverage is high.

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: retrieve a single conversation by id. 'One conversation by id' clearly distinguishes it from sakari_list_conversations, though it does so by implication rather than explicitly naming the list sibling.

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?

Routes the agent to sakari_list_messages with conversation_id when messages are actually needed, which is the main adjacent need. It doesn't state when to prefer this over sakari_list_conversations, but the single-item vs list distinction is clear from the purpose sentence.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds the returned field set (text, direction, status, segments, price, error), which is useful since no output schema exists, but says nothing about not-found errors or auth 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?

Front-loaded with the core action and return fields in a single tight sentence; the appended endpoint path is redundant with the tool's purpose but harmless. Minimal waste overall.

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 field list in the description compensates well for what to expect on return. Only minor gaps remain, such as error/not-found behavior for an invalid id.

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 message_id parameter is documented in-schema as "Sakari message id." The description's "by id" 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 resource (one message by id) and enumerates the returned fields, clearly distinguishing it from the sibling list_messages. It stops short of explicitly naming the alternative, so it's a strong 4 rather than 5.

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

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

"One message by id" implies the usage context versus list_messages, but there is no explicit when-to-use or when-not guidance. The selection rationale is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the REST path, which reveals that the account scope comes from context rather than a parameter, but says nothing about error behavior (e.g. unknown template id) 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 very short, front-loaded fragments with no filler. The raw endpoint path is mildly redundant with the tool's purpose but does clarify scope; nothing is bloated.

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

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

For a simple one-parameter read with no output schema, the definition is minimally sufficient, but it leaves the agent guessing what a template object contains and how failures surface. The structured annotations carry the safety profile, so the remaining gap is modest rather than critical.

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 template_id is documented in the schema, so the description adds no parameter meaning beyond it. Not that it needs to add much for a one-param lookup, but it does not explain id format or source.

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: fetches one message template identified by id, which implicitly distinguishes it from the sibling list_templates. It does not explicitly name that sibling, but the 'one ... by id' phrasing makes the single-item scope unambiguous.

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

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

Usage is only implied: an agent can infer this is the single-template lookup versus list_templates, but there is no explicit when-to-use statement or precondition, such as needing a template_id obtained from the list call.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the concrete endpoint path GET /v1/accounts/{accountId}/autoresponders, which is useful context, but says nothing about pagination, result limits, or whether it reads across all sub-accounts.

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 what the resource is, with zero filler. The trailing endpoint path is slightly redundant but still informative, and nothing is buried.

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

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

For a zero-parameter read tool with annotations covering safety, the definition is close to sufficient, but with no output schema it still never hints at what an autoresponder record contains or how many are returned. A single clause on return shape would close the 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?

The tool takes zero parameters, and the schema documents that fully, so there is nothing for the description to compensate for. Baseline 4 applies; the endpoint fragment at least shows the accountId is injected in the path rather than supplied by the caller.

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 ('autoresponders configured on the account') and parenthetically defines it as 'automatic replies', which a reader can map to a listing operation. It lacks an explicit verb, but the name supplies 'list' and the resource scope is unambiguous against siblings like list_templates or list_webhooks.

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 related tools (e.g., sakari_get_account for account-level config) and no mention of prerequisites such as needing an accountId or permission scope. The agent must infer usage entirely 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by identifying the data as voice call history and naming returned fields, but it does not discuss pagination, permissions, or rate limits beyond what annotations and schema provide.

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 compact and front-loaded: it first states what the tool returns and then lists filter dimensions. The endpoint is appended only as lightweight implementation context, with no wasted 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?

For a filtered list tool with no output schema, the description gives enough information about returned fields and filter dimensions. Pagination and parameter details are handled by the schema, though sorting or default ordering is not mentioned.

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 75%, and the schema already documents most parameters including date range, pagination and IDs. The description adds value by grouping the filters into contact, conversation, direction, status and date range, but it does not provide syntax or defaults 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 clearly states a specific resource and action: voice call history with direction, status, duration and contact. It implies the list-vs-get distinction through 'history' and filters, but does not explicitly name sibling tools such as sakari_get_call.

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 lists applicable filters, which implies browsing or searching call history, but it does not explicitly say when to use this tool instead of sakari_get_call or related list tools. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint path and the shape of returned data (schedule/template/status/reporting), but says nothing about ordering, pagination limits beyond the schema, or how large the result set can get.

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

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

Two short sentences, with the primary purpose front-loaded. The trailing raw endpoint path is low-value filler for an agent that already has a typed schema, but it costs only a few words.

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

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

With no output schema, the description does the minimum needed by enumerating the returned facets, and pagination is fully covered by the schema's offset/next_offset text. What's missing is whether results are ordered and whether archived or draft campaigns are included.

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% – name, limit and offset are each documented in the schema, including the next_offset continuation hint. The description adds nothing on parameters, so the baseline 3 applies.

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

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

States a clear verb+resource ("List message campaigns") and names the field content returned (schedule, template, status, reporting). The list-vs-get distinction from sibling sakari_get_campaign is implicit in the verb but never explicitly stated.

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

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

There is no guidance on when to use this versus sakari_get_campaign for a single campaign, or versus sakari_list_messages when campaign data is really what's needed. The only usage hint is the embedded endpoint path, which is not guidance an agent can act on.

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, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds genuinely useful behavioral context the annotations cannot: that matching is substring-based ("partial matches") on name, mobile and email, which changes how an agent should interpret result sets and filter values. It omits pagination behavior and result shape, keeping it below a 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?

One front-loaded sentence stating the operation and filter semantics, plus a short endpoint reference. Nothing is padded, though the GET /v1/... path largely restates what the readOnly annotation and schema already convey, so it earns slightly less than full marks.

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 7 optional params, 100% schema coverage and annotations present, the core is covered. But the description never mentions that results are paginated and that next_offset from the reply should feed the offset parameter (the schema references next_offset that is never defined here), nor what a contact record contains — a meaningful gap for a list tool with no output schema.

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

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

Schema coverage is 100%, so every parameter (tags, email, limit, offset, first_name, last_name, mobile) is already documented with defaults and ranges. The description only gestures at the same fields ("name, mobile or email; filter by tag") without adding syntax, combination semantics or matching rules beyond the partial-match note. Baseline 3 applies when the schema carries the load.

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 or search contacts") and clarifies that matching is partial on name, mobile or email and that tag filtering is supported. This separates it from sakari_get_contact and sakari_create_contact by implication, though no sibling is named explicitly.

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

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

Usage is only implied: the word "search" plus the filter parameters suggest this is the tool for browsing/finding contacts without an ID. It never states when to prefer sakari_get_contact (known ID) or when to use sakari_create_contact, and gives no prerequisites or exclusions.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about what the listing surfaces per conversation, including contact, last message, unread count, and open/closed state, which is valuable because there is no output schema.

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

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

The description is a single compact sentence with the main purpose and scope front-loaded, followed by useful field context and the endpoint. 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 simple two-parameter list tool with no output schema, the description supplies the key returned fields and the endpoint, while the schema covers pagination. It is nearly complete, though it could say more about ordering or filtering behavior.

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 schema already explains limit and offset including defaults and next_offset usage. The description adds no parameter-level detail beyond the schema, so the 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?

The description states a clear verb and resource, 'List conversations,' and adds scope with 'the inbox' plus the key fields shown. It does not explicitly distinguish itself from siblings like sakari_get_conversation or sakari_list_messages, so it stops short of a 5.

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

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

The parenthetical '(the inbox)' implies the tool's usage context, but there is no explicit guidance on when to use this versus get_conversation or list_messages. It is adequate but leaves alternative-tool routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that each form is returned with active state, impressions and conversions, but says nothing about pagination behavior, result ordering, or rate limits.

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

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

Two short sentences with no filler, and the data fields an agent cares about are front-loaded. The raw endpoint path is arguably redundant with tool metadata but is compact enough not to hurt.

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

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

For a simple, fully-annotated list tool with a 100%-documented schema, the main missing element is any statement of what the response looks like in aggregate (total counts, paging metadata) since no output schema exists. The brief field list partially compensates but leaves the return shape underspecified.

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 (q, limit, offset) are fully documented in the schema at 100% coverage, including the next_offset paging hint, so the baseline is 3. The description adds no filtering or paging semantics beyond what the schema already provides.

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

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

The description names the resource and the notable data it carries ('Lead capture forms with active state, impressions and conversions') plus the REST endpoint, so an agent can infer a read/list operation. However, it never states the operation with a verb — the listing behavior comes from the name and GET path, not the text, and nothing separates it from sibling list_* tools beyond the resource noun.

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 about when to use this tool, when not to, or which sibling to pick; the agent must infer from the resource name alone. Prerequisites such as needing an accountId are only visible via the endpoint string, not spelled out.

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 destructiveHint=false, so safety is covered. The description adds value by disclosing the returned fields and the REST path, but says nothing about pagination, result caps, or account scoping beyond the path template. Adequate but not 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?

Two short fragments with no filler; the payload description leads and the endpoint follows. It is efficient, though the fragmentary style leaves it slightly telegraphic.

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 does well to name the returned fields, but omits whether results are paginated or bounded and what the accountId path component implies for the caller. Somewhat complete for a simple read, with clear remaining 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 'q' parameter is documented in the schema as a cross-field search term. The description adds no meaning beyond that, which is the expected baseline when the schema already does the work.

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 resource (shortened tracked links) and enumerates the fields it carries (destination, short URL, click stats), plus the underlying endpoint GET /v1/accounts/{accountId}/links. The 'list' verb comes from the name/title rather than the description, and there is no explicit differentiation from the many sibling list_* tools beyond the resource noun.

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 versus alternatives such as sakari_list_campaigns or sakari_list_forms, nor any mention of the optional 'q' search parameter as a usage path. The only guidance is an endpoint path, which tells an agent nothing about selection or preconditions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results include sent and received messages and which fields come back, but says nothing about pagination defaults, rate limits, or auth scoping beyond the endpoint path.

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 compact sentence front-loads the resource and return payload, then appends the filter options and endpoint path. Every clause carries information; 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?

There is no output schema, so the description carries the burden of describing returns, and it does list the key response fields. It could go slightly further on pagination behavior (next_offset from the schema) but is otherwise sufficient for a read-only list tool.

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

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

Schema description coverage is 100%, so all four parameters (limit, offset, contact_id, conversation_id) are already documented in the schema. The description only restates that contact and conversation can be used as filters, adding no format or combination semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List messages') and enumerates the returned attributes (status, segments, price, timestamps) plus the two filter dimensions. The 'list' vs sibling 'sakari_get_message' distinction is implied by the verb rather than stated, so it is clear but not explicitly differentiated.

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

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

The filter options ('filter by contact or conversation') imply when this tool is appropriate, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., 'for a single message use sakari_get_message'). Usage must be inferred from the 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds only the endpoint path, with nothing about ordering, page-size defaults, or what a template object contains — the gaps are real but the bar is lower given annotation coverage.

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 fragments, front-loaded with the purpose, with zero filler. The trailing endpoint string is nearly redundant with the description, slightly costing it a point on tightness.

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 filtered-list tool with full schema coverage and safety annotations, the description is minimally sufficient. However, there is no output schema, so the description would ideally sketch the shape of a returned template; it does not.

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%: name, limit and offset are all documented in-schema, including the useful "Pass the previous reply's next_offset" hint. The description contributes nothing beyond that, 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+resource ("List reusable message templates") and reinforces it with the underlying endpoint path. An agent can distinguish this from sakari_get_template and sakari_create_template on the name alone, so the description doesn't need to spell out the 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?

No statement of when to reach for this versus sakari_get_template (single lookup) or sakari_list_autoresponders/other list tools. Usage is only implied by the verb "List"; there are no exclusions or prerequisites 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that only active subscriptions are returned and gives the REST path, but it does not explain the implicit account scoping (the path takes accountId yet the schema has no parameters) or whether pagination applies.

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 fragments, front-loaded with the resource, with no filler. The trailing endpoint path is marginally redundant for an agent but is compact and does convey the resource hierarchy.

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

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

With no output schema, the description carries the burden of describing the return value, yet says nothing about what a webhook record contains (target URL, subscribed event types) or how many come back. For a simple zero-argument list tool that is an acceptable but incomplete definition.

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

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

Zero parameters, which is the baseline-4 case; nothing needs disambiguating in the schema. The description's reference to an accountId path segment is a small extra hint that account context is supplied implicitly rather than by argument.

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 precisely ('Active webhook subscriptions') and clarifies it with 'message event notifications', so an agent knows this lists notification endpoints rather than something else. The verb is only implied by the tool name, and there are no semantically similar siblings to differentiate against, so a 4 rather than 5.

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

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

Usage is only implied: an agent can infer it should call this to discover configured webhooks. There is no statement of when to prefer it, no prerequisites, and no note about what to do when the list is empty or which sibling to use next (e.g., message or conversation tools).

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

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

Goes well beyond the annotations by disclosing cost against account balance, irreversibility ('cannot be recalled'), TCPA/CTIA compliance enforcement and sender liability, the aggregate 100-recipient cap, and per-contact placeholder substitution. These are consequences an agent cannot infer from destructiveHint/idempotentHint alone.

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?

Everything critical is front-loaded in the first clause (write, real messages, cost, irreversible); no filler sentences, and the trailing POST path is a compact scoping detail. Reasonably dense but each sentence carries a distinct constraint.

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-param destructive mutation with no output schema, the description covers cost, reversibility, consent, confirmation, and recipient limits. It does not say what comes back (message ids/status) or how partial failures behave, which would help an agent verify a send.

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 baseline 3 applies, but the description adds two things the schema does not: the 100 cap is a total across all recipient arrays (schema caps each at 100 individually), and {{firstName}}-style placeholders are resolved per contact. Recipient identifier types are restated rather than newly explained.

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 ('SEND REAL TEXT MESSAGES') and resource, and the 'WRITE:' prefix immediately distinguishes it from the read-oriented siblings (get_message, list_messages). The endpoint and channel types (SMS/MMS via media) make the scope 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?

Explicit about when-and-how: only text opted-in people, confirm recipients and text with the user first, and the recipient identifier options are enumerated. It lacks a named alternative ('to draft or preview, use X') but the conditions for correct use are 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?

Goes well beyond the annotations (destructiveHint/true, idempotentHint/true) by explaining the non-obvious replace semantics: it reads the current contact and sends it back whole, preserving lists, opt-in, blocked state and attributes while applying only the caller's changes. That is exactly the context an agent needs to not fear clobbering unmentioned fields on a destructive-looking tool.

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

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

Two sentences with zero filler, front-loading the mutation type and target before the behavioral caveat and the endpoint. Nothing repeats the title or annotations verbatim.

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 six-parameter write tool with no output schema and only partial parameter descriptions, the read-modify-write explanation covers the highest-risk unknown. It is slightly thin on the request shape (which fields pair with which, required contact_id) and says nothing about the response.

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 50% and the description only names the three loosely-described fields (name, email, mobile). It adds nothing about contact_id being required, the mobile/country pairing constraint, or first_name vs last_name, leaving the schema to carry the rest.

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?

Opens with an explicit verb-and-mutation marker ("WRITE: change a contact's name, email or mobile") naming the exact resource and fields affected. It also names the concrete endpoint, so an agent can distinguish it from sakari_create_contact and sakari_get_contact 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?

The "WRITE" prefix and the required contact_id context make it clear this is for modifying an existing contact rather than creating one. It does not explicitly name an alternative for creating or reading a contact, so the exclusions are only implied.

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