Bird MCP by usefulapi

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

The annotations declare destructiveHint=true, while the description explicitly characterizes the operation as 'additive' and states it 'sends no message' — a direct negation of the destructive semantic the annotation asserts. Per the scoring rule, a description that contradicts annotations scores 1 and is flagged.

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 core action front-loaded and no padding. The trailing 'Bird API: POST /v1/audiences' is marginally useful context for API-aware agents but is largely restating what the tool does.

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 three-parameter create tool with no output schema, the description covers the essential add-audience behavior and the static-empty caveat. It does not say what comes back (e.g. the new audience identifier), whether contacts can be attached at creation time, or anything about permissions, and the conflict with destructiveHint leaves the safety profile ambiguous.

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, type (with an enum) and description, giving a baseline of 3. The description only adds the fact that 'static audiences start empty', which touches on the type parameter but adds no format or constraint 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?

The description gives a specific verb+resource ('Creates an audience (contact list) in Bird') and clarifies the resource type, making it distinguishable from list/get siblings and from the message-sending tools. However, it never names a sibling it is not, so differentiation is more implicit 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as bird_create_contact or bird_list_audiences. 'Static audiences start empty' is a behavioral fact rather than a usage routing cue, leaving the agent to infer the call context.

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

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

With only destructiveHint=true provided, the description adds meaningful context: the operation is additive, it triggers no outbound message, contacts are unique by email (implying duplicate handling), and it names the underlying endpoint. There is mild tension with destructiveHint=true since "additive" under MCP semantics aligns with a non-destructive hint, but the term reads as "inserts a new record / sends nothing" rather than a read-only claim.

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 clauses with zero filler. The identifying purpose, the behavioral note, and the API path are each packed into a single sentence and nothing is repeated.

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-record create tool with no output schema, the description covers purpose, side-effect profile, uniqueness, and endpoint, which is nearly enough to call it confidently. It stops short of noting what is returned (e.g., the created contact id) or how duplicate-email conflicts surface, which a mutation with no output schema could benefit from.

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%, including the nested "data" object and its property-creation dependency, so the schema already documents all five parameters. The description only restates the email uniqueness constraint that the schema also notes, adding no new parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ("Creates a contact (CRM record) in Bird") and even names the API endpoint (POST /v1/contacts). The clause "additive, sends no message" distinguishes it from the messaging siblings in the same server, so an agent can place it without opening the schema.

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

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

The description implies usage (create a CRM contact) and clarifies it does not send a message, which nudges against the sibling messaging/audience tools. However, it never states when to use this over bird_get_contact or bird_create_audience, nor any prerequisite like verifying the contact doesn't 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=true, so the safe-read profile is covered. The description adds the underlying API mapping (GET /v1/audiences/{audience_id}), which is useful locator context, but says nothing about not-found errors, permissions, or return shape; with annotations doing the safety work, a 3 is appropriate.

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; the core action is front-loaded and the API mapping trails as supporting detail.

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 single-resource read with full schema coverage and readOnlyHint annotations, the definition is nearly sufficient. No output schema exists, so return values needn't be explained; only the lack of error/not-found behavior keeps it from a 5.

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

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

Schema coverage is 100% and there is only one parameter, audience_id, fully documented in the schema. The description's endpoint path reinforces where the id goes but adds no format or syntax detail beyond the schema, matching the baseline.

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 ('Fetch') and resource ('a single audience by id'), clearly distinguishing it from the sibling list_audiences. It does not explicitly name the sibling it contrasts with, so it falls just short of the top score.

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

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

The description gives no explicit when-to-use guidance, prerequisites, or named alternatives. The 'single audience by id' phrasing implies the lookup scenario, but the agent must infer when this beats list_audiences.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying API mapping (GET /v1/contacts/{contact_id}), which is contextual but not behavioral – it says nothing about what happens when the id is missing/not found or what the payload contains. With annotations carrying safety, a 3 is appropriate.

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 before the API detail. Nothing is padded, though the Bird endpoint line is of marginal value to an agent deciding whether to call the tool.

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

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

For a simple read-only point lookup with one fully documented parameter, no output schema, and readOnlyHint covering safety, the description is close to sufficient. The only meaningful gap is error/not-found behavior, which is minor for this tool class.

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

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

Schema description coverage is 100% and the single parameter contact_id is fully documented in the schema. The description only restates 'by id' and adds no format, prefix, or validation 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: 'Fetch a single contact by id.' The word 'single' implicitly distinguishes it from the sibling bird_list_contacts, so an agent can tell it is the point-lookup rather than the list operation. It stops short of explicitly naming the alternative, keeping it at 4 rather than 5.

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

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

Usage is implied by 'by id' – the agent infers this is the tool to use when it already has a contact_id. However, there is no explicit when-to-use/when-not guidance and no reference to bird_list_contacts for the case where no id is known, which is the main routing decision here.

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

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

The readOnlyHint annotation already declares this a safe read. The description adds the underlying API path (GET /v1/email/messages/{message_id}), which is weak extra context, but says nothing about auth requirements, 404/not-found behavior, or rate limits. With annotations covering the safety profile, this meets the minimum bar without exceeding 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?

Two short, front-loaded sentences with the purpose first and no padding. The trailing API-path sentence earns its place only marginally, keeping this 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?

For a one-parameter read tool with readOnlyHint and no output schema, the description covers what the agent needs to call it correctly. Missing error/not-found behavior is a minor gap given the simplicity.

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% for the single parameter and the schema already documents 'Email message id.' The description's 'by id' adds no format, prefix, or sourcing detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('Fetch') and resource ('a single email message by id'), which cleanly separates it from the list counterpart bird_list_email_messages and from the SMS/WhatsApp getters by channel. It does not explicitly name those siblings, but the resource phrasing is unambiguous.

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

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

'by id' implies the tool is used when a message id is already known, but there is no explicit when-to-use statement, no mention of prerequisites like obtaining the id from bird_list_email_messages, and no exclusions. Usage is only weakly implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint mapping (GET /v1/sms/messages/{message_id}), which is mildly useful context, but it says nothing about error behavior for a missing/invalid id or what the payload contains.

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

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

Two short sentences, front-loaded with the purpose, with no filler. The endpoint reference is arguably redundant with the tool name but is 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 tool with annotations covering safety and a fully documented schema, this is adequate. With no output schema, the agent gets no hint about the returned message fields, though that is a minor gap for a simple getter.

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?

Only one parameter, message_id, and schema coverage is 100%, so the schema fully documents it. Baseline 3 applies; the description adds no format or sourcing detail beyond the schema's 'SMS message id.'

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

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

States a specific verb and resource ('Fetch a single SMS message by id'), which cleanly separates it from the sibling bird_list_sms_messages. It does not, however, explicitly name the list sibling or note that it returns one record vs many, so sibling differentiation is only implied by 'single ... by id'.

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

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

There is no guidance on when to use this versus bird_list_sms_messages or the other get_* siblings. It says what it fetches but never conditions, 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, so the safe-read profile is covered. The description adds the underlying HTTP endpoint (GET /v1/whatsapp/messages/{message_id}), which is mildly useful context, but nothing about error cases for missing ids or what the payload contains.

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

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

Two compact sentences, front-loaded with the action and resource, with the endpoint path as supplementary detail. No wasted words.

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

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

For a trivial one-parameter read tool with no output schema, the description covers what it does and the identifier used. Only minor gaps remain (no note on behavior for unknown ids, no pointer to the list tool for discovering ids).

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% for the single message_id parameter, so the schema already documents its meaning. The description adds no format, syntax, or sourcing detail beyond what the schema provides, 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 (fetch) and resource (a single WhatsApp message) and scopes it to lookup by id, which implicitly separates it from the sibling list_whatsapp_messages. It does not name that sibling explicitly, but the 'single ... by id' phrasing is enough to distinguish single-fetch from list.

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

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

'By id' implies the prerequisite of already having a message id, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., list_whatsapp_messages for discovery). Usage context is inferable 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, so safety is covered; the description adds the pagination model (cursor page) and the underlying REST endpoint, which is real context beyond annotations. It does not state default page size, max limits, or rate-limit behavior, so it is not fully transparent.

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 with the purpose and pagination behavior front-loaded and no filler. The endpoint reference is compact and skippable for agents that don't need 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?

For a 3-parameter read-only list tool with full schema coverage, the description covers purpose, scoping, and the paging model. With no output schema, it leaves the actual response shape (e.g., what next_cursor is returned alongside) only implied rather than stated.

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

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

Schema description coverage is 100%, so limit, audience_id, and starting_after are already documented, including the reference to next_cursor. The description's 'cursor page' phrasing reinforces starting_after but adds no syntax or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb (List), resource (contacts), and scope (belonging to a static audience) rendered as a cursor page. The 'static audience' qualifier cleanly separates it from bird_list_contacts, so an agent can route without opening either schema.

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

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

The 'static audience' scoping implicitly tells the agent this tool is for audience-scoped listing and not for the dynamic/segment case, and it names the parent resource. There is no explicit 'use X instead when Y' routing to a sibling, so it stops short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses two real behavioral traits: ordering ('newest first') and pagination model ('as a cursor page'), plus the backing endpoint GET /v1/audiences. It does not describe auth requirements or rate limits, so it is 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?

Two sentences, zero filler, with scope and ordering front-loaded before the endpoint reference. Every clause carries information an agent can use.

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

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

For a zero-required-parameter list tool with a fully documented schema, ordering plus pagination semantics are the critical missing pieces and both are present. No output schema is supplied, so the description could say a bit more about the page shape, but it is essentially sufficient.

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

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

Schema description coverage is 100%, so both limit and starting_after are already fully documented in the schema, including the next_cursor relationship. The description's phrase 'cursor page' merely echoes that; with the schema doing the heavy lifting, the baseline 3 is correct.

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

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

The description states a specific verb and resource ('List audiences') and clarifies the domain term by equating audiences with contact lists, which helps distinguish it from bird_list_contacts and bird_list_audience_contacts. It does not explicitly name a sibling to route against, so it stops short of a 5.

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

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

Usage is implied by the verb and scope ('in the workspace'), but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as bird_list_audience_contacts for listing people inside a list. An agent can infer the intent but gets no routing help.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main addition is the underlying REST endpoint. It does not disclose pagination behavior or result ordering, though the cursor parameter hints at paging. Adequate given annotations carry the safety profile.

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 stated first and the API reference appended compactly. No filler, no redundancy with 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?

For a zero-required-parameter read-only list tool with no output schema, this covers what the tool returns at a high level ('definitions/schema') and where it comes from. It stops short of describing the shape of each returned property object, which is the only real remaining gap.

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

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

Schema description coverage is 100%, with both limit and starting_after fully documented in the schema, including the next_cursor linkage. The description adds no parameter detail, so the baseline of 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the custom contact-property definitions (schema) for the workspace'), which clearly separates it from bird_list_contacts that returns contact records. It doesn't explicitly name a sibling to contrast with, but the resource is precise enough for an agent to disambiguate.

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 tool returns schema definitions, so an agent infers it should call this to discover property definitions rather than contact data. There is no explicit when-to-use, when-not-to-use, or named alternative among the many bird_list_* siblings.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds genuinely useful context beyond annotations: newest-first ordering, cursor-paged results, and the underlying endpoint (GET /v1/contacts). It still says nothing about auth scopes, rate limits, or page-size defaults.

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

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

One front-loaded sentence carrying resource, scope, ordering and pagination form, followed by a short API-reference line. Nothing is wasted.

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

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

For a simple read-only list tool with no output schema, the description covers scope, ordering and pagination mechanism, which is enough to call it correctly. Minor gaps are the absence of filter/alternative guidance, which is not strictly needed here.

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

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

Schema description coverage is 100% and both parameters (limit, starting_after) are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List contacts (CRM records)'), plus scope ('in the workspace') and ordering ('newest first'). The workspace scope implicitly separates it from bird_list_audience_contacts and bird_get_contact, but no sibling is named outright.

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: fetch all workspace contacts, advancing with a cursor. There is no explicit statement of when to prefer this over bird_list_audience_contacts or how to filter, 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, so the safety profile is covered. The description usefully adds ordering ('newest first') and pagination model ('cursor page'), but says nothing about result fields, rate limits, or what happens when the workspace has no messages.

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 ordering and pagination semantics front-loaded and an endpoint reference tacked on for orientation. Nothing redundant or padded.

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

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

For a read-only list tool with no output schema, the description covers pagination mechanics but not the shape of a returned message or how next_cursor surfaces in the response. Adequate but leaves the agent to infer the return contract.

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

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

Schema description coverage is 100%, so both limit and starting_after are already documented in the schema; the description only echoes the cursor concept. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List email messages') plus scope ('sent from the workspace'), which separates it from bird_get_email_message and the SMS/WhatsApp list siblings. It does not explicitly name those siblings, but the resource noun is unambiguous.

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

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

Usage is implied by the list-vs-get naming and by the cursor/ordering note, but the description gives no explicit when-to-use guidance, no preconditions, and does not point to bird_get_email_message for fetching a single 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?

With readOnlyHint=true already covering the safety profile, the description still adds real behavioral context beyond the annotations: results are workspace-scoped, include both directions, are sorted newest first, and are returned as a cursor page, plus the underlying API endpoint. It stops short of disclosing auth requirements, rate limits, or empty-page 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?

A single tight sentence that front-loads the resource and scope, then appends the pagination model and endpoint. No filler, nothing repeated from the schema.

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

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

For a two-parameter read-only list tool with full schema coverage and no output schema, the description covers scope, ordering, and pagination, which is what an agent needs to call it. It omits any hint about the shape of returned items and error/empty behavior, 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 both parameters (limit, starting_after) are already documented in the schema, and the description adds no syntax or semantic detail beyond echoing the cursor-page concept. Baseline 3 applies when the schema carries the parameter burden.

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), resource (SMS messages), and scope (inbound + outbound, for the workspace), plus ordering (newest first) and paging model (cursor page). This is enough for an agent to distinguish it from bird_get_sms_message and bird_list_sms_templates 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?

Usage is implied by the resource scope and the pagination note, but there is no explicit when-to-use guidance, no statement of when to prefer this over sibling list tools, and no prerequisites or exclusions. Adequate but with clear gaps.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description usefully discloses that the result set mixes system built-ins with workspace-owned templates, plus the backing endpoint, but says nothing about pagination, ordering, or result 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?

Two short sentences, front-loaded with the resource and its scope, followed by the API reference. Nothing is redundant or padded.

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

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

There is no output schema, so the description could carry more, but it does convey the identity and origin of returned items. Missing pagination/result-size behavior keeps it from a 5; for a zero-required-param read-only list tool it is otherwise sufficient.

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

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

Schema description coverage is 100% with two enums, so all three filters are already documented in the schema. The description adds no filter syntax or value semantics beyond what the schema provides, making 3 the correct baseline.

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

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

States a clear verb+resource ('List the SMS templates') and adds meaningful scope: results include Bird built-ins plus workspace templates. It does not explicitly differentiate from the sibling bird_list_whatsapp_templates, so it stops short of a 5.

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

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

No when-to-use guidance and no alternatives named. An agent has to infer from the name that this is a discovery/enumeration step, and nothing tells it when another list tool (e.g., bird_list_whatsapp_templates) would be the right choice instead.

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 cover readOnlyHint, so the description carries the rest and does add real value: it discloses that both inbound and outbound messages are returned, that results are newest-first, that pagination is cursor-based, and even names the underlying endpoint. It stops short of describing the per-message payload, which the missing output schema leaves undocumented.

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 plus the API reference line; scope, direction, ordering, and paging form are all front-loaded with no filler.

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

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

For a two-parameter, filterless list tool with no output schema, the description covers what is returned (both directions, newest first, cursor-paged). What each message record contains is left unstated, but that is a modest gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so both limit and starting_after are already documented in the schema. The description adds no parameter-level detail (e.g., default page size or cursor semantics), so the baseline 3 applies.

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

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

States a specific verb (list) and resource (WhatsApp messages) with scope (workspace), direction (inbound + outbound), ordering (newest first), and pagination style (cursor page). The channel-specific resource name cleanly separates it from bird_list_sms_messages and bird_list_email_messages.

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

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

No indication of when to use this listing tool versus bird_get_whatsapp_message or bird_list_whatsapp_templates. The scope phrase 'for the workspace' describes behavior, not selection criteria, so the agent must infer usage from the name 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, so the safety profile is covered. The description adds the underlying API endpoint (GET /v1/whatsapp/templates), which is mildly useful context, but says nothing about pagination, result size, or freshness of the template 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 short, front-loaded sentences with no filler: the purpose first, then the endpoint reference. Every element earns its place.

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

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

For a zero-parameter list tool with readOnlyHint annotations and no output schema, the description is nearly sufficient. Missing only minor operational detail such as whether the list is paginated or filtered by channel status.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already shows.

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 (WhatsApp message templates) with the scope 'available to the workspace'. An agent can distinguish it from bird_list_whatsapp_messages or bird_list_sms_templates by the resource wording, though the description never explicitly names an 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?

Usage is only implied by the description: fetching templates for the workspace. There is no statement of when to prefer this over bird_list_whatsapp_messages or the SMS template tool, nor any prerequisites or exclusions.

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