Textline MCP by usefulapi

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

Annotations already declare the write/non-destructive/non-idempotent profile, but the description adds real behavioral context: the note is agent-only and never delivered to the customer, plus the concrete endpoints used. It omits idempotency/reversibility detail, which the annotations partially cover.

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

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

A single front-loaded sentence led by the 'WRITE:' tag; the visibility constraint and targeting options are packed in with no filler, and every clause earns its place.

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

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

For a write tool with no output schema, the description plus annotations and full-coverage schema give an agent enough to call it correctly: purpose, visibility semantics, and both targeting paths. It could be stronger with an explicit note about the resolve flag's side effect, but nothing essential 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%, so all five parameters are already documented, including the 'pass this OR' targeting and the open-on-missing behavior. The description restates the uuid/phone_number targeting without adding format or constraint 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 (add) and resource (internal whisper/note) scoped to a conversation, and the parenthetical 'never sent to the customer' implicitly distinguishes it from textline_send_message. It stops short of naming the sibling explicitly, so it's clear but not fully differentiated.

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

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

The visibility distinction ('note only your agents see, never sent to the customer') implies when to prefer this over send_message, and it explains the two targeting modes. However, there is no explicit when/when-not statement or named alternative, leaving the 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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds genuinely useful context beyond them by clarifying that no message is dispatched to the contact and by naming the underlying endpoint, which tells the agent this is a silent record write rather than a messaging action.

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 fragments, front-loaded with the operation class and the core action, with nothing padded. The trailing endpoint reference adds little for an agent but costs only a few tokens.

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?

As a creation tool with annotations but no output schema, the description covers the essential what and the key non-obvious behavior (no message sent). It omits what is returned on success and whether re-posting the same phone number creates a duplicate or returns the existing contact, which is notable given idempotentHint=false.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema with formats, lengths, and patterns. The description contributes no additional parameter meaning, 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?

States a specific verb and resource: 'add a contact (customer) to the Textline address book', which an agent can easily separate from textline_get_customer and textline_update_customer. The 'WRITE:' prefix reinforces the operation class, though it does not explicitly contrast with the closest siblings.

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 WRITE label and 'add' verb indicate a creation operation. There is no explicit statement of when to prefer this over textline_update_customer, nor any prerequisite such as required permissions or how duplicates by phone number are handled.

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

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

Annotations already cover readOnly, idempotent, non-destructive and openWorld, so the safety profile is handled. The description adds real value by disclosing the returned fields (name, permission level, on_call availability, departments) and the underlying endpoint, which is meaningful given 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?

A single tight sentence, with the resource and lookup keys front-loaded and the returned fields trailing; every clause earns its place.

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

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

For a small read-only lookup with fully documented params, this covers what an agent needs, and it partially compensates for the absent output schema by naming returned fields. It stops short of explaining behavior when both keys are omitted or how the two keys interact.

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

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

Schema coverage is 100% with patterns and descriptions for both email and user_uuid, so the schema carries the parameter burden. The description restates the two lookup keys but adds no format or precedence detail (e.g., which wins if both are given), so baseline 3 is appropriate.

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

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

States a specific verb (Retrieve) and resource (one agent/user), names the two lookup keys (UUID or email), and enumerates the returned fields. This clearly differentiates it from the sibling list_agents, which returns many.

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 implies single-record lookup but never explicitly says when to use this vs textline_list_agents or what to do if neither email nor UUID is supplied (0 required params). Usage context is implied, not stated with alternatives 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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond that by disclosing the ordering (newest page first) and the composition of returned posts, including internal whispers and resolve/transfer events, which an agent could not infer from the schema.

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

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

Two dense sentences with zero filler; the core purpose and the ordering constraint are front-loaded, and the paging alternatives and endpoint follow compactly.

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 compensates by describing what the returned posts contain and how they are ordered. Pagination modes are covered; only the choice against sibling retrieval tools is absent, which is a minor gap for a well-specified read 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 five parameters are already documented in the schema. The description adds only that before_uuid/after_uuid are post uuids and that the two paging styles are alternatives, which is marginal beyond the schema's 'exclusive' notes.

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

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

States a specific verb (Retrieve) and resource (one conversation and its posts), enumerates what posts include (messages in/out, internal whispers, resolve/transfer events), and notes ordering (newest page first). It is clearly distinguishable from siblings like list_conversations and get_conversation_by_phone.

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 explains how to page (page/page_size or before_uuid/after_uuid), which is useful invocation guidance, but it never states when to choose this tool over list_conversations or get_conversation_by_phone. Usage context is implied by 'one conversation' rather than made explicit.

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, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the useful fact that posts/messages are included in the response, but says nothing about pagination behavior or the department-defaulting when group_uuid is omitted (that lives only in the schema). Modest added value over 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?

One tight sentence, front-loaded with the action and resource. The trailing raw endpoint fragment ('GET /api/conversations.json?phone_number=…') is the weakest part since it restates structured information, but it is short and does not 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 read-only lookup with no output schema, the description names the retrieval key, the resource, and that messages are returned alongside the conversation. Pagination and department-default behavior are covered by the schema. Only the absence of an explicit alternative-tool route 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% – all six parameters (page, page_size, before/after_uuid, group_uuid, phone_number) are documented in the schema with defaults, ranges, and cross-references. The description only gestures at the phone_number and department concept, adding no syntax or 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 ('Retrieve') and resource ('the conversation with a phone number... and its posts'), plus the lookup key. An agent can tell it fetches a conversation by phone rather than by UUID. It does not explicitly name the sibling textline_get_conversation as the alternate lookup path, so it falls short of the 5 bar.

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: 'if you have a phone number, this gets that conversation and its messages.' There is no explicit when-to-use vs. textline_get_conversation or textline_get_customer_by_phone, and no stated prerequisites (e.g., whether the contact must already exist).

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the REST path (GET /api/customer/{uuid}.json), and stays silent on auth requirements, error/not-found behavior, and what fields come back.

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 action and the lookup key front-loaded; nothing is padded. The raw endpoint string is mildly redundant for an agent but not wasteful.

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 rich annotations, the description covers the essentials of selection and invocation. With no output schema, though, it should at least sketch the returned contact payload or note that a missing UUID yields an error, which 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?

There is a single parameter and schema description coverage is 100%, with the UUID format pattern documented in the schema itself. The description only restates that the lookup key is a UUID, adding no syntax or semantic detail 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 ('Retrieve one contact (customer)') plus the lookup key ('by UUID'), which implicitly separates it from list_customers and get_customer_by_phone. It stops short of naming those siblings explicitly, so an agent must infer that UUID-keyed retrieval is the unique scope of this 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?

The phrase 'by UUID' implies the precondition for using this tool, and the sibling get_customer_by_phone makes the alternative obvious by contrast. However, no explicit when-to-use, when-not-to-use, or fallback guidance (e.g. 'if you only have a phone number use get_customer_by_phone') is 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered structurally. The description adds the concrete endpoint (GET /api/customers.json?phone_number=...), which is useful context, but says nothing about not-found behavior, error responses, or what happens with ambiguous/multiple matches.

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

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

Two short sentences with zero filler, and the core action plus lookup key are front-loaded. The trailing raw HTTP endpoint is mildly redundant against the structured schema but still compact.

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 with full annotations this is close to adequate, but the description omits the not-found/empty-result behavior and does not characterize the returned contact object. With no output schema present, a brief note on the return payload would have been worthwhile.

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% — the single phone_number parameter already carries its own description plus a format pattern and maxLength. The description adds no syntax, normalization, or E.164 guidance 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 (Retrieve), resource (one contact/customer from the address book) and the lookup key (phone number), which is more precise than its title. It does not explicitly distinguish itself from the sibling 'textline_get_customer' (lookup by another key) or 'textline_get_conversation_by_phone', leaving the reader to infer the difference.

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

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

The phrase 'by phone number' implies the selection condition (use this when you only have a phone number rather than the customer ID used by textline_get_customer), but there is no explicit when-to-use statement, no exclusions, and no mention of the alternative tools. Usage must be inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds only the HTTP endpoint (GET /api/organization.json) and the shape of what is returned; it says nothing about auth requirements, rate limits, or response nesting.

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 action front-loaded and no padding. The trailing endpoint path is marginally redundant but harmless.

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 tool with zero required parameters, full annotation coverage and a fully documented schema, the description tells the agent what is returned (org name, optionally departments and agents). With no output schema, it does not detail the response structure, which is a minor gap.

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

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

Schema description coverage is 100% and both booleans are self-documented ('Include the agents (users)', 'Include the departments'). The description merely restates their effect, adding no syntax or default-value detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Retrieve the organization (account) name') plus the optional expansion into departments and agents, which is more precise than the tautological title. It does not explicitly differentiate itself from siblings such as list_departments or list_agents, leaving the agent to infer that this is the org-level roll-up.

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

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

The phrase 'optionally with its departments and agents' implies when the include flags are useful, but there is no explicit when-to-use guidance or routing to alternatives like list_departments/list_agents for those collections separately.

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, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds useful context by disclosing the underlying endpoint (GET /api/organization.json?include_users=1) and the returned field set, but says nothing about pagination, auth requirements, or result size for an org-wide listing.

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: the value proposition (what agents are listed and which fields come back) is front-loaded, with the endpoint detail placed last. No redundant restatement of the title or annotations.

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 parameters, the description must carry the return-value burden, and it does so by naming the fields returned. Annotations cover the safety profile, so nothing material is missing for correct invocation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The field enumeration describes the response shape rather than input semantics, which is helpful but not required.

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 (agents/users in the organization) and enumerates the fields returned: name, email, UUID, permission level, availability, department UUIDs. It is clearly distinct in scope from the singular get_agent sibling, though it never names that 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?

No when-to-use guidance, no prerequisites, and no mention of the get_agent alternative for retrieving a single agent. Usage is only implied by the verb 'list' — an agent must infer the selection condition 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the structured fields: results are grouped one-per-contact and each carries contact and resolved status, and it identifies the underlying GET 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?

Three compact clauses with the core scope ('list conversations one per contact in a department') front-loaded, followed by the optional-search note and endpoint. No wasted wording.

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?

All four parameters are schema-documented, annotations fully cover the read-only/idempotent profile, and no output schema exists so return values need not be explained. The description is sufficient to call the tool correctly, with only sibling routing left implicit.

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 (page, query, page_size, group_uuid) are already documented in the schema. The description only echoes the optional keyword search and adds no format or syntax detail beyond that, which is the baseline when the schema does the heavy lifting.

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

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

The description gives a specific verb (List) and resource (conversations), plus the useful granularity 'one per contact' and the department scoping. It implicitly distinguishes itself from the singular textline_get_conversation, but does not name that or any other 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?

The phrase 'Optional keyword search' hints at when the query parameter is relevant, but there is no explicit when-to-use vs. alternative guidance. An agent must infer that this is the broad listing tool rather than textline_report_conversations or the single-conversation getter.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the concrete endpoint (GET /api/customers.json) and the returned field surface, which is useful but not a deep behavioral disclosure; pagination defaults live only in the schema.

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

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

A single compact sentence that front-loads the action and resource, then closes with the raw endpoint. 'contacts (customers)' is slight redundancy but useful name-mapping rather than waste.

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's field enumeration (name, phone, email, tags, notes, custom fields, consent, reachability) usefully signals what comes back. Pagination and search semantics are adequately handled by the schema, leaving little an agent would still need.

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% – page, query, and page_size all carry their own descriptions including defaults and max values. The description contributes nothing about 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 specific verb pair and resource ('List or search contacts (customers)') and even disambiguates the colloquial vs API naming. It enumerates the address-book fields covered, so an agent can distinguish it from textline_get_customer, but it never names the sibling retrieval tools explicitly.

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

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

The 'list or search' phrasing implies the browse/filter use case, but there is no explicit when-to-use guidance against textline_get_customer, textline_get_customer_by_phone, or textline_list_saved_searches. No exclusions or preconditions are stated; usage must be inferred from the name and 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds useful context beyond that: the scope is the address book, the payload shape (name, data type, UUID), and the fact that these UUIDs feed an update call. It does not discuss pagination or response envelope, which keeps 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?

Two short sentences: purpose first, cross-tool usage second, endpoint last. Every clause carries information 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?

With no parameters and no output schema, the description carries the burden of describing the return value, and it does so by naming the three fields returned. That plus the cross-tool pointer is everything an agent needs to call this correctly.

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

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

The tool takes zero parameters, which is the baseline-4 case. There is nothing for the description to disambiguate, and it correctly signals that this is an unfiltered list operation.

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 address book's custom fields') and even enumerates the returned fields (name, data type, UUID). No sibling lists custom fields, and the reference to textline_update_customer makes the tool's position in the workflow 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?

Explicitly tells the agent the downstream purpose of the result: 'Use the UUIDs with textline_update_customer.' That is a clear, actionable usage cue. It stops short of any when-not guidance or comparison against alternatives, but none is really needed for a single-purpose list 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real context beyond them: the results are scoped to what 'the token's agent can see', the concrete return fields are enumerated, and the valid department types (sms, facebook, smart_sms) are disclosed, which hints at the data domain.

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

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

A single sentence front-loads the action, resource, scope and return shape, with the endpoint appended. No filler, no repetition of the title.

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

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

With no output schema, the description carries the return-value burden and does list the fields returned (name, UUID, phone number, type, member agent UUIDs). It does not mention pagination, result limits, or whether empty results are possible, which is a minor gap 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?

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline for a no-argument tool is 4. Nothing is missing on this dimension.

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 departments') and disambiguates the term inline with synonyms ('groups / inbox phone lines'), so an agent can distinguish it from textline_list_agents or textline_list_customers without opening any schema. It also names the endpoint, anchoring the tool to a concrete API resource.

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 rather than stated: the agent learns this returns the departments visible to the token's agent, which is a useful scoping cue, but there is no explicit when-to-use/when-not or named alternative (e.g., vs. textline_list_agents). Adequate but leaves the choice 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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that dispositions are pre-configured account-level values and that filtering is optional, but says nothing about result ordering, pagination, or volume limits on the returned list.

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

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

Two tight sentences: the scope statement comes first, the follow-on integration hint and endpoint second. No filler, no redundancy with the title or annotations.

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-optional-parameter read-only list with no output schema, the description covers purpose, scope, and downstream consumption, which is sufficient. It is only slightly light on what the response contains, but that gap is minor for a tool this simple.

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 group_uuid parameter is already documented in the schema. The description's phrase 'optionally for one department' restates the filter intent and clarifies the domain meaning of the UUID without adding format or behavior 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 (List) and resource (dispositions, glossed as resolution reasons) with clear account-level scope and an optional department narrowing. An agent can immediately distinguish this from sibling list tools like textline_list_departments or textline_list_surveys because the resource is unique and defined.

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

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

Explicitly ties the tool into a workflow by noting its UUIDs are consumed by textline_resolve_conversation, which tells the agent why and when to call it. It stops short of stating when NOT to use it or naming an alternative tool for related lookups, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond them by naming the returned fields (name, description, UUID) and the underlying endpoint, which matters because there is no output schema to document the return 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 operation and resource, and every clause carries information. The raw endpoint path is the only element of marginal value to an agent.

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

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

For a no-parameter, no-output-schema list tool with full annotation coverage, the description supplies the resource identity, the scope (one address book), and the returned fields. Only pagination or result-size behavior is left unspecified.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a parameterless list call and does not invent or misdescribe arguments.

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 (saved searches), and disambiguates the domain term by equating it with 'contact segments'. The resource is unique among siblings, so no explicit sibling contrast is needed, but none is given either.

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, when-not-to-use, precondition, or alternative mentioned. Usage is only inferable from the name and the object it lists, which is the bare minimum implied-guidance case at best.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the useful default of a 30-day window and the fields returned, but says nothing about result caps, pagination, or ordering for a potentially large response set.

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 plus an endpoint path; the core purpose and the field list are front-loaded. The raw 'GET /api/survey/{uuid}/responses.json' adds little for an MCP caller and is the one element that does not fully earn 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?

With no output schema, the description does the right thing by sketching the returned fields, and read-only annotations cover the safety profile. Missing pagination/size expectations for a responses listing, but otherwise complete for a simple filtered read.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description contributes information the schema lacks — the default date range when start_date/end_date are omitted. That is genuine added meaning for the two optional date parameters, though formats are left to the schema.

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

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

States a specific verb and resource ('List the responses to one survey') and even enumerates the payload fields (ratings, follow-up text, contact, tags). It is readily distinguished from textline_list_surveys, though it never names that sibling, so differentiation is implicit rather than explicit.

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: you call this when you have a survey UUID and want its responses, and the 'Default: the last 30 days' note tells the agent what happens if the date params are omitted. There is no explicit when-not guidance or named alternative (e.g., textline_list_surveys for discovering UUIDs), so it stops short of a 4.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds only that the call is a GET and what the items contain (type and UUID); it says nothing about pagination, result limits, or auth requirements. Useful but thin 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 no filler, and the purpose is front-loaded ahead of the endpoint detail. The trailing 'GET /api/surveys.json' is marginally useful to an agent but is the only near-redundant element.

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 full annotation coverage, the description is nearly sufficient; it even partially compensates for the absent output schema by naming the returned fields. It stops short of describing result shape or ordering, so it is not 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?

The tool takes zero parameters, so the schema carries no semantic burden and the baseline is 4. The description correctly describes a no-argument list operation with no misleading parameter hints.

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 surveys) and enriches it with the survey categories covered (NPS, CSAT, custom) and the fields returned (type, UUID). It implicitly separates from the sibling textline_list_survey_responses, though it never names that 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?

Usage is implied by the name and the enumeration of survey types, but there is no stated when-to-use or when-not-to-use guidance, and no routing to textline_list_survey_responses for response data. An agent can infer the intent but gets no explicit exclusion.

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 readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the result set carries total_records, and continuation requires replaying the full next.* triple with filters preserved. It does not mention rate limits or auth requirements, so it stops short of 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 sentences, zero filler: purpose first, then the pagination contract, then the drill-down tool, closing with the endpoint. Every sentence supplies distinct information and nothing is repeated from the schema or annotations.

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 13 parameters, no required fields and no output schema, the description does the needed work by naming total_records and the next.* return shape, which is the main thing an agent must know to paginate. It could say a bit more about the absence of required params (group_uuid vs search_uuid dependency), which is only implied.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema only hints at: that next.search_uuid, next.page and next.page_size must be supplied together and that existing filters are retained implicitly. The group_uuid-as-department mapping is also restated usefully in prose.

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 a department's conversations') plus the filter dimensions (created/updated time, resolved, archived, blocked) and the reporting framing. It is clear, but it never distinguishes itself from the sibling textline_list_conversations, leaving the agent to infer why a reporting variant exists.

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

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

Gives an explicit follow-up action ('then use textline_report_posts per conversation') and precise pagination instructions (pass back next.search_uuid, next.page, next.page_size exactly, filters retained). What is missing is when to choose this tool over textline_list_conversations, so no full when/when-not/alternative coverage.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real operational context beyond that: this is a reporting endpoint, results include total_records, and pagination must reuse the returned next.search_uuid/next.page/next.page_size exactly. It stops short of describing return payload structure or rate limits.

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

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

Three compact sentences, front-loaded with purpose then pagination mechanics, then the raw endpoint. The endpoint path is arguably redundant but small; no filler prose.

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 compensates by naming key returned fields (creator, thread, first-response flags) and the pagination contract (total_records, next.*). Coverage is good for a read-only list tool, though the full post payload shape remains unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by emphasizing that pagination parameters must be passed back verbatim from the prior response and by noting created-time filtering semantics. This is genuinely useful beyond the schema text.

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/messages/whispers of one conversation), plus the returned fields (creator, thread, first-response flags, total_records). This clearly separates it from textline_get_conversation or textline_list_conversations, which operate on conversations rather than posts.

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?

Frames the tool as a reporting API scoped to a single conversation and gives explicit continuation instructions for paging. It does not, however, state when to prefer this over sibling tools or any prerequisites (e.g. needing a conversation UUID first).

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior. The description adds genuine context beyond them: nothing is sent to the customer, and the exact endpoint (POST /api/conversation/{uuid}/resolve.json) is disclosed. It stops short of describing error cases or what happens to an already-resolved 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?

Three tight fragments, front-loaded with the WRITE label and the core effect before the optional detail and endpoint. Every clause carries information; nothing is filler.

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

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

For a mutation tool with full annotation coverage and no output schema, the description covers side effects and the endpoint adequately. It omits any mention of failure modes or idempotent-repeat behavior (though the annotation hints at it), leaving a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value by clarifying that disposition_uuid is optional and must be sourced from textline_list_dispositions. It does not explain format details beyond what the schema already encodes.

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 resolved (closed)') and explicitly labels it as a WRITE operation. This clearly distinguishes it from read siblings like textline_get_conversation and from the other mutation sibling textline_transfer_conversation.

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

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

Names the companion tool for obtaining the optional disposition value (textline_list_dispositions), giving the agent a concrete path before invoking. It does not state when NOT to resolve (e.g., versus transferring), so it falls short of full when/when-not 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 only flag destructive/non-idempotent/open-world, while the description adds the critical real-world consequences: the customer receives it immediately, it cannot be unsent, and it consumes message credits. It also discloses the two write endpoints, which is beyond anything structured data provides.

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?

Four tight sentences with the irreversible/costly nature front-loaded, then addressing, then constraints, then endpoints. The all-caps opener is emphatic but functional; no sentence is 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?

Covers irreversibility, credit cost, recipient limits, addressing modes, and endpoints for a high-stakes mutation tool with no output schema. It stops short of describing the response or failure modes (e.g., invalid number), so it is strong but not exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the uuid-vs-phone_number XOR and the optional department. The description restates the addressing modes rather than adding format, validation, or default details 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+resource+scope: sends a real SMS/MMS to exactly one contact from the user's Textline number. It is immediately distinguishable from siblings like textline_create_customer, textline_resolve_conversation, and textline_transfer_conversation without opening any schema.

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

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

Gives concrete addressing guidance (conversation_uuid OR phone_number + optional department) and clear exclusions: 'One recipient per call; no bulk sends,' plus a pre-send confirmation step. It does not name a sibling alternative, but the constraints are unambiguous.

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 description adds real behavioral context beyond the annotations: 'Nothing is sent to the customer' clarifies there is no customer-visible side effect, and the endpoint confirms the operation shape. Annotations already cover the safety profile (idempotent, non-destructive, open-world), so this addition is a meaningful bonus rather than a necessity.

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

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

A single tightly-packed sentence plus the endpoint path. The WRITE prefix and assignment action are front-loaded, and no sentence is wasted.

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

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

For a 3-parameter mutation with no output schema, the description covers purpose, effect on the customer, and the alternate identifier inputs. It omits error behavior (e.g. what happens if the target agent is in another department) and whether the conversation's prior assignment is recoverable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value by clarifying that assignee and user_uuid are mutually exclusive ('one of them') — a relationship the JSON schema alone cannot express. The schema still supplies the UUID/email formats, so this is added, not substituted.

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 (WRITE/assign) and resource (conversation) with the exact effect: reassigning to another agent of the same department. It is clearly distinguishable from siblings like textline_resolve_conversation and textline_send_message, which do different things to a conversation.

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

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

Gives clear context for use: transferring within the same department, with no customer-facing notification. It does not name alternatives (e.g. resolve_conversation) or state when NOT to use it, so it falls short of the top score despite the useful constraints.

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 readOnly=false, destructive=true and idempotent=true, and the description usefully adds two things they don't: that only the fields you pass are overwritten (partial update, not a full replace of the record) and that no notification is sent to the contact. It omits permission/auth requirements and any error behavior, keeping it out of the top band.

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, the mutation mode front-loaded, the destructive/overwrite semantics placed before the endpoint detail. No filler; every clause carries information an agent needs.

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 mutation with a nested object and no output schema, the description covers mutation mode, field scope, overwrite behavior, tag-handling modes and the UUID dependency. Return values need not be explained since no output schema exists; only auth/permissions and failure behavior remain unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents name, email, notes, tags and custom_fields formats. The description's only real additions are the source of custom-field UUIDs and the add/remove/replace vocabulary for tags, which the schema already enumerates. 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?

Opens with an explicit verb and mode ('WRITE: update a contact') and enumerates exactly which fields can be changed (name, email, notes, tags, custom fields). It also names the sibling tool that supplies custom-field UUIDs, so an agent can distinguish it from read tools like textline_get_customer without opening a 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 'WRITE:' prefix and the pointer to textline_list_custom_fields make usage context clear: this is the mutation path for an existing contact, and custom-field keys must be sourced from the listing tool first. It stops short of stating exclusions (e.g. use textline_create_customer for new contacts), so it is context without alternatives.

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