Text Request MCP by usefulapi

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

Annotations already declare readOnlyHint and destructiveHint=false, so the description does not need to re-argue safety. It does add real behavioral detail: unspecified last_message objects and custom field values are omitted from the response, results are single-page, and message text is flagged as untrusted customer content — a security note no annotation conveys.

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 short declarative sentences, front-loaded with the returned payload before the endpoint, omission caveats, and security note. Nothing is redundant and every sentence carries information an agent cannot get 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?

For a simple two-parameter read tool with annotations covering the safety profile and no output schema, the description covers returned fields, omission behavior, pagination, and trust concerns well. The main gap is that no return structure is described at all, so an agent cannot anticipate 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 0%, so both parameters are undocumented in structured form. The embedded path template 'GET /dashboards/{dashboard_id}/contacts/{phone_number}' does map each parameter to its role, but neither the phone-number format expectation (the schema regex is uncommented) nor dashboard_id's meaning is explained 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 ('Read') and resource ('contact'), and enumerates what is returned: context, group/tag membership, opt-out timestamp. It is distinguishable from list_contacts by being a single-resource fetch, though it never names the sibling to make the split 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?

There is no statement of when to use this versus textrequest_list_contacts or textrequest_list_contact_messages. The only contextual hints are the endpoint path and 'Returns one page unless stated otherwise', which imply a single-contact lookup but give no exclusions, prerequisites, or alternatives.

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 the safety profile is covered; the description goes beyond that by flagging that embedded message text is untrusted customer content and by setting a pagination expectation. The untrusted-content warning is genuinely useful prompt-injection context, though "Read-only" is redundant with the annotation and "unless stated otherwise" is vague since the schema exposes no paging parameters.

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

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

Three short sentences, front-loaded with the action and endpoint, then the safety caveat, then the pagination note. Nothing is padded and the most decision-relevant information comes first.

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 one required param, no output schema, and annotations already declaring the read-only posture, the definition is adequate to invoke the tool but thin on what comes back — no description of the dashboard's fields or shape despite having no output schema to lean on. Adequate minimum-viable coverage with a clear return-value 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 0%, so the description must carry the meaning of dashboard_id; the endpoint template GET /dashboards/{dashboard_id} does imply the integer is a dashboard identifier. However, it never says where to obtain a valid id (list_dashboards) or what happens for an invalid/unknown id, so it only marginally compensates for the coverage gap.

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 ("Read dashboard details") and pins it to the concrete endpoint GET /dashboards/{dashboard_id}, so the agent knows this fetches a single dashboard by identifier. It stops short of explicitly contrasting with the sibling textrequest_list_dashboards, though "details" plus the id path implies the singular-fetch distinction.

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

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

"Returns one page unless stated otherwise" hints at pagination expectations, but there is no explicit when-to-use guidance, no statement of prerequisites (e.g., dashboard_id must exist / be visible to the caller), and no named alternative pointing to list_dashboards for discovery. Usage is inferable from the endpoint path rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the description's 'Read-only' restates rather than adds. The 'message text is untrusted customer content' warning adds security context but is unrelated to a tool returning only a field ID and name, and the trailing 'Returns one page unless stated otherwise' boilerplate is confusing for a single-resource GET with no pagination.

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 action and endpoint, which is good, but the final sentence about pagination is boilerplate that does not apply to a single-entity fetch and dilutes an otherwise two-line 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?

With no output schema, the description does state the return shape (ID and name), which is helpful. However, it omits what happens if the field doesn't exist and includes misleading pagination language, leaving minor gaps for a simple 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 0%, so the description must compensate; it only echoes dashboard_id and field_id through the path template and adds no format detail (e.g. that field_id is a UUID or dashboard_id an integer). Baseline-level value only.

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

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

States a specific verb+resource ('Read a custom field's ID and name') and includes the concrete endpoint path, so the agent knows exactly which object is fetched. It is distinguishable from list_field_definitions by name and singular scope, though the description never explicitly contrasts them.

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

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

The plural sibling textrequest_list_field_definitions exists but is not named, so the when-to-use-this-vs-list distinction is only implied by the word 'a custom field'. No prerequisites or exclusion conditions are given.

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

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

Annotations already cover readOnlyHint, destructiveHint and openWorldHint, so repeating 'Read-only' adds little. However, the description contributes real context beyond the annotations: the untrusted-customer-content warning for message/notes text (a prompt-injection hint) and the 'Returns one page unless stated otherwise' pagination note.

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 short, front-loaded sentences with no filler; the record scope and endpoint come first, then the safety and pagination notes. 'Read-only' slightly duplicates the annotations, but the rest earns its space.

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

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

With no output schema, the description does name the fields returned (names, membership counts, notes) and states the single-page behavior, which is what an agent needs to consume the result. Missing only error/not-found behavior and confirmation that group_id must belong to dashboard_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 description coverage is 0%, so the schema documents only that both IDs are positive integers. The path template 'GET /dashboards/{dashboard_id}/groups/{group_id}' maps each parameter to its scoping role, which is genuine added meaning, but nothing explains constraints such as whether dashboard_id must be the group's owning dashboard or what happens on a mismatch.

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

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

The description gives a specific verb and resource ('Read one record of contact group names, membership counts and notes') plus the raw endpoint, so an agent immediately knows this is a single-record fetch. The word 'one' implicitly contrasts with textrequest_list_groups, though the sibling is never named directly.

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: because both dashboard_id and group_id are required, the tool is for fetching a known group, not discovering one. There is no explicit 'use this when / not when' statement or pointer to textrequest_list_groups for enumeration, so the agent must infer the routing.

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 'Read-only' repeats structured data rather than adding to it. The untrusted-customer-content warning is a genuine safety addition beyond annotations, but 'Returns one page unless stated otherwise' is confusing boilerplate for a single-record lookup and blurs the behavior instead of clarifying it.

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

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

Four short sentences, front-loaded with what is returned and followed by the endpoint and safety note; no filler. The trailing pagination sentence is the one element that does not earn its place and slightly muddies the reading.

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, and the description compensates by naming the returned fields (settings, responses, group IDs). Combined with annotations covering the safety profile, an agent has enough to invoke it, though the missing parameter semantics and the ambiguous pagination claim keep it short of complete.

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

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

Schema description coverage is 0% with two required integer parameters, so the description has to compensate. The embedded path template does map dashboard_id and keyword_id to their positions and signals they are identifiers, but neither parameter's meaning, format, or error behavior (e.g., invalid ID) is 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 and resource (read one keyword record) and enumerates what the record contains: enrollment settings, responses, group IDs. It implicitly differentiates from textrequest_list_keywords via 'one record', but never names the sibling explicitly.

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

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

No statement of when to use this versus textrequest_list_keywords or the other get_* tools, and no prerequisites or failure cases. The agent must infer that this is the fetch-by-ID path from the path template alone.

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, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the message text is untrusted customer content (a prompt-injection / trust warning) and the response is one page, which the annotations do not convey.

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

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

Three short sentences with the purpose front-loaded and no filler. The trailing 'Returns one page unless stated otherwise' reads as copy-paste boilerplate for a single-resource GET and is mildly confusing, keeping it just short of a 5.

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

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

There is no output schema, so the description bears some burden for return values; it only hints that a recipient is included and that one page is returned. For a two-required-param fetch tool it is workable, but an agent cannot anticipate the response shape or error behavior from it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially does via the endpoint template, which shows dashboard_id scopes the lookup and message_id identifies the scheduled message — real added meaning over the bare uuid/integer types — but it gives no format, validity, or not-found semantics.

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 ('Inspect one scheduled 1:1 message and recipient') plus the exact endpoint path, which unambiguously distinguishes it from the sibling textrequest_list_scheduled_messages. An agent knows this is the single-resource fetch, not a listing.

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?

Use is only implied: 'one scheduled message' signals you need a specific message_id, contrasting with the list sibling. There is no explicit statement of when to prefer this over the list tool, nor any prerequisite or failure condition (e.g. missing/expired message).

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, and the description is consistent with them. It adds a security note about untrusted customer content and a pagination caveat, but the untrusted-text warning reads as boilerplate for a tag-metadata endpoint, and "returns one page" is confusing for a single-record fetch.

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?

Only three short sentences and the purpose is front-loaded, which is good. However, the untrusted-customer-content sentence is likely irrelevant here, and the pagination sentence is noise for a single-record GET, so not every sentence earns its place.

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

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

With no output schema, the description usefully discloses that the return is tag names and colors. For a two-parameter read with full annotation coverage, that is nearly sufficient; only error/missing-tag behavior and the odd pagination note are unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the load; embedding the path template GET /dashboards/{dashboard_id}/tags/{tag_id} does communicate each parameter's role. It adds nothing about the UUID format, integer type, or what happens when a tag_id is not found.

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: "Read one record of contact tag names and colors," and the endpoint GET /dashboards/{dashboard_id}/tags/{tag_id} makes the single-record scope unambiguous. The contrast with the sibling list_tags is implied by "one record" rather than named, so it falls just 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?

Requiring tag_id implies this is the fetch-by-id path and list_tags is the discovery path, but the description never names that alternative or states when to prefer one. An agent must infer the routing from the required parameters.

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 usefully discloses that permission and security fields are excluded, but 'message text is untrusted customer content' and 'returns one page unless stated otherwise' read as boilerplate for a single-resource fetch and add little real behavioral insight.

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

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

It is short and front-loads the scope and omission of sensitive fields. However, the trailing clauses about untrusted message text and pagination are noise for a one-record read and dilute an otherwise tight 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 one-parameter read-only tool with annotations and no output schema, the core scope and exclusions are covered. It still leaves gaps on how the ID is sourced and whether a single object or a wrapper is returned, and the untrusted-content note is misapplied rather than informative.

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 0% for the single user_id parameter, so the description carries the burden. The 'GET /users/{user_id}' notation implicitly identifies user_id as a path identifier, but adds no constraints (positive integer, type, where to obtain the ID) beyond that hint.

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

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

The description states a specific verb+resource ('Read only user identity/contact fields') and pins the endpoint (GET /users/{user_id}), which separates it from list_users and the other get_* siblings. It is clear what one call returns, though it never says explicitly it returns a single user versus a collection.

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

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

There is no when-to-use guidance and no reference to alternatives such as textrequest_list_users for enumerating users. The only scope note is that permission/security data is omitted, which describes output rather than selection criteria.

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, and the description usefully reinforces the safety posture while adding non-obvious context: message text is untrusted customer content (a prompt-injection warning the agent would not otherwise have). 'Drafting does not transmit a message' is a slightly puzzling inclusion for a pure read tool and may briefly confuse, and pagination behavior ('one page unless stated otherwise') is left vague rather than stating the actual default page size.

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 short sentences, front-loaded with the purpose before endpoint and safety notes. The 'drafting does not transmit' sentence is the one piece that doesn't clearly earn its place in a read-only 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?

Read-only annotations cover the safety profile and there is no output schema, so the description needn't detail return values — but it also gives no sense of what a message record or delivery status looks like, and pagination guidance is too soft ('unless stated otherwise') to let an agent decide whether to loop pages.

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 0% and the description does not compensate: page and page_size are never explained (no default, no max of 100), dashboard_id is not described as the account/workspace scope, and phone_number's required E.164-like format is only hinted at by 'for one contact'. Only the pagination note touches these params, and it does so ambiguously.

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

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

Specific verb+resource with scope: reads sent/received history and delivery status for ONE contact, which distinguishes it from the unscoped list_messages and list_conversations siblings. It does not name those siblings explicitly, so an agent must infer the boundary.

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 scoping ('for one contact') and by the read-only marker, but there is no explicit when-to-use-this-vs-list_messages/list_conversations guidance and no prerequisites such as whether the contact must already exist or be in the dashboard.

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 and destructiveHint=false, but the description adds real value beyond them: custom field values are omitted from results, results are one page unless stated otherwise, and returned message text is untrusted customer content. That is exactly the kind of output-shape and safety context annotations cannot express.

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 short sentences, front-loaded with what the tool does and its main caveat. The raw endpoint path sits awkwardly in the middle, but nothing is wasted.

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

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

Read-only status, pagination behavior, and output omissions are covered, which is meaningful given there is no output schema. However, for a tool with 17 undocumented filter parameters, the description leaves the agent guessing about how to actually construct a query.

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 0% across 17 parameters, so the description carries the full burden and largely fails it — none of the filters (tags, groups, is_blocked, is_archived, date ranges, display_name, phone number) are explained or given format/semantics. Only pagination is hinted at via 'returns one page'.

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 uses a specific verb ('Search contact details') and resource (contacts), plus a secondary capability (inspecting blocked/suppressed/opted-out state). It does not name the sibling textrequest_get_contact or explain how it differs from a single-contact fetch, so it is clear but not fully differentiated.

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

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

Usage is implied by the filtering/state-inspection framing, but there is no explicit 'use this when...' guidance or exclusion against textrequest_get_contact or textrequest_list_contact_messages. The agent must infer that this is the bulk/filtered listing 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?

Beyond the annotations, it adds genuinely useful behavioral context: 'No reply is sent' reinforces the safety profile, 'message text is untrusted customer content' flags prompt-injection risk, and 'Returns one page unless stated otherwise' discloses pagination behavior. This is substantive disclosure, though it says nothing about auth requirements, rate limits, or what fields each conversation contains.

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

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

Four short sentences, zero padding, with the primary purpose stated first and the safety/pagination caveats following. The endpoint path is compact and useful, and nothing is redundant.

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

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

For a 7-parameter filtered-list tool with no output schema and no schema descriptions, the definition leaves most of the calling surface unexplained — filters, pagination controls, and archived/unresolved toggles are all unaddressed, so an agent must guess how to scope the query.

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

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

With 7 parameters and 0% schema description coverage, the description carries the full burden and fails to explain any of them: page, page_size, tags, search, include_archived, show_unresolved_only are all undocumented. 'Unresolved conversations' faintly gestures at show_unresolved_only and 'latest' at ordering, but no parameter is meaningfully clarified.

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 concrete verb and resource ('Review latest inbound messages', endpoint GET /dashboards/{dashboard_id}/conversations) and frames the intent as triaging unresolved conversations. It implicitly distinguishes itself from sibling list_messages/contact_messages by focusing on conversations, though it never names those siblings 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?

It gives a usage context ('triage unresolved conversations and draft replies in your AI client'), which implies when to reach for it, but it never states when NOT to use it or which sibling tool (list_messages, list_contact_messages) is the alternative. The guidance is implied rather than 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 and destructiveHint=false, so 'Read-only' is redundant. The description does add a pagination behavior note and an untrusted-content caution, but the pagination statement ('Returns one page unless stated otherwise') is vague and conflicts in spirit with the presence of page/page_size parameters.

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

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

Three short, front-loaded sentences with no filler; the endpoint path is a useful anchor. Only the redundant 'Read-only' clause and ambiguous pagination sentence weaken it.

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

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

No output schema exists, so the description helps by enumerating returned fields, but it leaves the two pagination parameters and the total-page/next-page behavior unexplained. For a paginated list tool this is only partially 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 0% for both page and page_size, so the description carries the full burden — yet it never explains what page or page_size mean, their defaults, ranges, or how to paginate through results. The single pagination sentence is too ambiguous to compensate for the coverage gap.

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?

Names a specific verb and resource and enumerates the fields returned (IDs, names, phone numbers, time zones), which distinguishes it from the singular textrequest_get_dashboard. It stops short of explicitly routing against that sibling, so it is clear but not fully differentiated.

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

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

Implies the use case (discover accessible dashboards before fetching one), but never states when to use this versus textrequest_get_dashboard or whether it is a prerequisite step. Usage must be inferred from the 'list' vs 'get' naming.

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 usefully adds that contact field values are omitted and that results are unpaginated. However it then says 'Returns one page unless stated otherwise', which sits in tension with the no-pagination claim, and the 'message text is untrusted customer content' note is boilerplate that doesn't apply to field definitions.

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

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

The text is short and leads with the key fact (IDs and names only), but it reads as stitched-together fragments, and the untrusted-message sentence adds noise rather than value for this resource.

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 important work of stating what comes back (IDs and names, no values) and that results aren't paginated, which is exactly what an agent needs to decide whether to call it. The main remaining hole is the unexplained dashboard_id parameter.

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 0% and the single parameter dashboard_id is never mentioned in the description, so the agent gets no explanation of what dashboard the fields belong to or what happens for an invalid/missing ID. With one undocumented parameter, the description fails to compensate for the schema gap.

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 concrete resource (field definitions, IDs and names only) and gives the underlying endpoint GET /dashboards/{dashboard_id}/fields. It implicitly contrasts with the singular sibling get_field_definition by emphasizing a bulk list of IDs/names, though it never says so 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?

'Read field IDs and names only' implies the use case (need identifiers/labels rather than values), but there is no explicit when-to-use or when-not guidance and no mention of the natural alternative, textrequest_get_field_definition. The agent must infer the choice between list and singular.

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. The description adds useful context that results are paged and that message text is untrusted customer content, but it does not cover authorization needs, rate limits, or other operational behavior.

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

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

The description is short and front-loaded with the main purpose and endpoint. The untrusted-content note is security-relevant but somewhat tangential for a group-listing tool, so it is not perfectly economical.

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, and the description does list the returned fields, which helps. However, with 0% parameter description coverage, it omits pagination parameter semantics and does not fully explain how to page through results.

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 0%, so the description must compensate, but it only implies dashboard_id via the endpoint path. It says nothing about page or page_size, leaving two of the three parameters undocumented in both schema and description.

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

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

The description states a specific verb and resource: reading contact group names, membership counts, and notes. It also gives the endpoint. It is clear it is a list operation, though it does not explicitly name get_group as the single-group alternative.

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

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

The description does not say when to use this tool versus alternatives such as get_group, nor does it state prerequisites or exclusions. The listing purpose is implied by the name, but there is no explicit usage 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 real value beyond that: it flags that message text is untrusted customer content (a prompt-injection caution) and notes the one-page default return unless stated otherwise. It stops short of describing auth requirements or pagination totals.

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

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

Three short sentences with the operation and its scope front-loaded, followed by the trust warning and the pagination note. Nothing is padded, though the endpoint path restates the resource already named in sentence one.

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 0% schema description coverage, the description should say more about the parameters and the shape of the returned keyword records. It partially compensates by naming what comes back (enrollment settings, responses, group IDs) but leaves page/page_size and dashboard_id selection unexplained.

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

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

Schema description coverage is 0% for all three parameters, so the description must carry the load. It implies that dashboard_id scopes the result through the endpoint path and hints at paging with 'returns one page,' but it never explains what page and page_size do, their bounds, or how dashboard_id must be chosen. Two of three parameters remain effectively undocumented.

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 ('Read keyword enrollment settings, responses and associated group IDs') and pairs it with the concrete endpoint GET /dashboards/{dashboard_id}/keywords. The 'list' naming plus the plural resource clearly distinguishes it from the sibling textrequest_get_keyword, though the description never says so 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 endpoint path (list keywords scoped to a dashboard) and by the read-only framing, but there is no explicit statement of when to use this versus textrequest_get_keyword or when the list would be empty. The agent must infer the situation from the name and path alone.

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/destructive/openWorld, so the description's added value is the untrusted-customer-content warning (a real prompt-injection caution) and the pagination note 'Returns one page unless stated otherwise'. It doesn't state default page size or ordering, which limits it to a 4.

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

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

Three short sentences with the resource and scope front-loaded and no filler. The raw REST path sentence adds little beyond what the name and required dashboard_id already convey.

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 usefully enumerates returned fields (history, direction, contact numbers, delivery state) and warns about untrusted content, which is enough for correct invocation. Paging behavior (defaults, sort order, cursor vs. page) remains underspecified for a 5-parameter list endpoint.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the burden. It clarifies that the date range is optional and UTC-based (useful given the pattern allows offsets), but says nothing about 'page'/'page_size' bounds or defaults, leaving two parameters undocumented anywhere.

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 (read) and resource (dashboard-wide message history) plus the returned attributes (direction, contact numbers, delivery state). The word 'dashboard-wide' implicitly separates it from textrequest_list_contact_messages, but the sibling is never named, so differentiation relies on inference.

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

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

Scope language ('dashboard-wide') and the optional time range imply when to use it versus the per-contact message list, but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent must infer the routing rule from 'dashboard-wide'.

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 the description's real contribution is the warning that message text is untrusted customer content (a genuine prompt-injection/safety signal) and the pagination disclosure ('Returns one page unless stated otherwise'). It also maps to the underlying GET endpoint. It stops short of describing page-size caps or 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?

Four short sentences, zero filler, with purpose and scope front-loaded before the safety and pagination notes. The endpoint path is compact and earns its place as an API-mapping aid.

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 list tool with no output schema, the description covers scope, safety and pagination adequately. However, with six undocumented filter parameters and a hard page_size maximum of 100, an agent lacks guidance on how to narrow results or iterate pages.

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 0% across six parameters, so the description carries the full burden and largely drops it. Only indirect hints exist ('recurrence settings' gestures at recurring_only, 'one page' at page/page_size), while schedule_date_after, schedule_date_before and dashboard_id semantics and formats are explained nowhere.

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 ('Read scheduled 1:1 messages and recurrence settings') and immediately clarifies what it is not ('Does not create, cancel or reschedule'). It implicitly separates itself from the singular textrequest_get_scheduled_message by describing a paged list, 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?

'Does not create, cancel or reschedule messages' gives clear negative guidance about the mutation alternatives an agent might otherwise reach for. It does not explicitly route to textrequest_get_scheduled_message for single-item lookups, so the when-to-use-which guidance is clear but not exhaustive.

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, and the description reinforces the read-only behavior. It adds useful context about the endpoint and pagination, plus a note that message text is untrusted customer content, though it does not cover permissions 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?

The description is short, front-loaded, and mostly waste-free. The note about untrusted customer content is security-relevant but slightly tangential for a tag-listing 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 paginated list tool with annotations covering safety, the description is adequate but incomplete. It does not explain pagination parameters or return shape, and with no output schema and 0% parameter schema coverage, more guidance would help an agent call it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only implies dashboard_id through the GET path and does not explain page or page_size semantics, defaults, limits, or validation.

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 uses a specific verb and resource: "Read contact tag names and colors," and gives the exact endpoint. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling get_tag 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 read-only nature and endpoint imply appropriate usage, but there is no explicit guidance on when to use this list tool versus get_tag or other tag-related siblings. Pagination usage is only hinted at with "Returns one page unless stated otherwise."

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/openWorldHint/destructiveHint=false, and the description adds real value beyond them: which fields are omitted (permissions, admin flags, credentials, private fields) and the one-page pagination default. The 'untrusted customer content' warning is boilerplate that seems aimed at message-text tools rather than a user directory, which weakens the signal.

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?

Compact and front-loaded with the purpose, endpoint and read-only status in the first few clauses. The untrusted-content sentence is the one element that doesn't clearly earn its place for a user-listing 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?

With no output schema, the description usefully names the returned fields and states which are stripped, plus the paging behavior. But it leaves the entire filter/pagination parameter surface undescribed, so an agent can't confidently build a filtered or paginated call.

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 four parameters (page, page_size, email, external_user_id) have 0% schema description coverage, so the description carries the full burden and fails: it never says these act as filters, never explains the page/page_size defaults or the 100 max, and never confirms email/external_user_id are exact-match lookups.

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 ('look up') and resource ('user names, emails and external IDs') with the endpoint GET /users. It differentiates from list-only siblings implicitly but never contrasts with textrequest_get_user, so single-vs-list selection is left to inference.

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

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

'for assignment/context' hints at the intended use case, but there is no explicit statement of when to call this instead of textrequest_get_user, nor any note that the optional email/external_user_id params narrow the list.

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