Nylas MCP by usefulapi

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

The description asserts the operation is 'safe/additive' while the annotation declares destructiveHint=true — a direct conflict in the safety profile an agent uses to decide whether to call the tool. The description would otherwise add useful context (non-sending semantics, REST endpoint), but the explicit contradiction of the structured hint invalidates that.

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 waste, and the most consequential constraint (does not send) is front-loaded ahead of the implementation detail. Nothing can be removed without losing selection-relevant information.

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 6-parameter creation tool with no output schema and bare annotations, the description covers the key behavioral fact (it creates, does not send) and the endpoint, but omits what comes back (draft id?), where the draft lands (drafts folder), and any auth/grant requirements. Adequate but with visible gaps.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (to, cc, bcc, body, subject, grant_id). The description adds only implicit signal about grant_id by showing it in the URL path; it contributes no field-level semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Creates a draft email') and immediately carves out the boundary with the most confusable sibling by asserting it 'does NOT send'. An agent can separate this from nylas_send_message without opening either schema, though other siblings (e.g. nylas_list_drafts) are not addressed.

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

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

The parenthetical 'does NOT send' implies the selection condition (use when you want to stage a message rather than dispatch it), but it never states when to prefer this over nylas_send_message, nor any prerequisites such as a valid grant. Usage is implied rather than spelled out.

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

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

Annotations supply only destructiveHint=true, so the description adds real value: it discloses that the call 'may send invites to participants' (an external side effect not covered by annotations), notes calendar_id is sent as a query param, and documents the v3 endpoint. It still doesn't explain auth requirements or reversibility of a destructive-flagged create.

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

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

Three tight sentences with the core action front-loaded and no filler. The endpoint URL is somewhat technical overhead but does orient the agent, so it is not 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 an eight-parameter mutation with no output schema, the description covers the required calendar_id and the invite side effect but says nothing about the return value, error behavior, or permission/auth needs. Adequate but with clear gaps for a destructive-flagged create tool.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including their types and the calendar_id query-param placement. The description's only repeated note about calendar_id being a query param adds nothing beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Creates a calendar event'), and the create action is easily distinguished from read/query siblings like nylas_get_event and nylas_list_events. It stops short of explicitly contrasting with the closest sibling (nylas_create_draft) or scoping the creation target.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives. The description states mechanics but leaves the agent to infer that this tool is for new events versus retrieving or updating existing ones.

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, and the description adds nothing behavioral beyond that — no error behavior (e.g., 404 for an unknown id), no auth/permission notes, no rate-limit context. The endpoint string is the only extra detail and is purely structural.

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; the second sentence is a compact API reference rather than padding. Nothing is wasted, though the second sentence is of marginal value to an agent.

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

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

For a simple single-resource read with no output schema and fully documented parameters, the description is adequate; return values need not be explained. Only the absence of failure-mode context (unknown id, missing grant) keeps 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 100%, with both grant_id and calendar_id fully documented in the schema. The description only echoes 'by id', adding no syntax, format, or defaulting details beyond the schema 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 and resource ('Get a single calendar') and the 'single ... by id' phrasing implicitly contrasts with the sibling nylas_list_calendars. It is clear, though it never names the sibling alternative explicitly.

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

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

There is no when-to-use guidance, no statement of prerequisites, and no routing to nylas_list_calendars when the id is unknown. The only context given is the underlying REST endpoint, which is not 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, covering the safety profile. The description adds the REST endpoint mapping, which usefully shows grant-scoped path access, but it omits error behavior (e.g., not-found handling), auth requirements, and response shape. That is adequate but not rich.

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

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

Two short sentences with the core action front-loaded and no filler. The endpoint reference is compact and earns its place for API-oriented agents.

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-record read with full schema coverage and readOnly annotations, the definition gives enough to invoke correctly. It does not describe the returned contact object, but no output schema exists and that omission is minor.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The endpoint string in the description echoes that grant_id and contact_id are path parameters but adds no syntax or format detail beyond the structured fields, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Get a single contact by id') and scopes it to one record, which implicitly contrasts with the sibling nylas_list_contacts. It stops short of explicitly naming the list alternative, so it is clear but not maximally 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: call this when you have a contact_id and need the full record. There is no explicit when-to-use vs when-not, no mention of the list_contacts alternative, and no prerequisites such as required scopes or valid grant 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the concrete API shape (GET /v3/grants/{grant_id}/events/{event_id}) and notes calendar_id is a query param, but says nothing about failure modes (e.g. missing event/calendar) or auth requirements.

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

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

Two short sentences, front-loaded with the core action, followed by the required-param caveat and the raw endpoint. Nothing extraneous and 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 low-complexity fetch-one tool with full schema coverage and a readOnly annotation, the description supplies the action, the required param behavior, and the underlying endpoint path. The only gap is that with no output schema, it does not hint at what the returned event object contains.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the 'sent as a query param' note. The description's restatement of calendar_id's query-param behavior duplicates rather than extends the schema, so baseline 3 applies.

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

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

The description states a specific verb+resource ('Get a single calendar event by id'), and the word 'single' implicitly contrasts with the sibling nylas_list_events. It never names that sibling explicitly, so sibling differentiation is left to inference rather than stated.

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

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

Usage context is only implied by 'by id' - the agent can infer this is the fetch-one operation rather than a list. There is no explicit when-to-use, no exclusions, and no pointer to nylas_list_events as the alternative for browsing.

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 this is a safe, non-mutating read, so the description does not need to establish that. It adds the underlying REST mapping (GET /v3/grants/{grant_id}), which is minor context, but says nothing about auth scope requirements, what fields are returned, or error/not-found behavior.

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

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

Two short sentences with no filler, and the purpose is front-loaded ahead of the API mapping. The endpoint line adds marginal value for an agent that already has a typed tool interface, but it is not wasteful enough to penalize much.

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 a full-coverage parameter schema, readOnly annotations, and no output schema to explain, the description covers what is needed to call it correctly. Only the lack of routing guidance toward nylas_list_grants keeps it from being fully complete.

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

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

Schema description coverage is 100% and the single grant_id parameter is already documented in the schema, including the NYLAS_GRANT_ID override behavior. The description only echoes {grant_id} via the endpoint path, adding no semantics beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get details for a single connected account') and disambiguates the Nylas jargon 'grant' by equating it with 'connected account'. The word 'single' implicitly distinguishes it from nylas_list_grants, though that sibling is not named explicitly.

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

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

Usage is only implied: 'a single ... grant' suggests fetching one known grant versus listing all, but there is no explicit when-to-use, no prerequisites, and no named alternative (e.g. nylas_list_grants) to route the agent. Adequate but with a clear gap.

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 Nylas v3 REST path, which helps orient the agent to the API surface, but it says nothing about auth requirements beyond the grant scope, error behavior, or what a fetched message 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 with the core action front-loaded and no padding. The REST endpoint reference is marginally useful but is the only sentence that could be trimmed.

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 with no output schema, the description is minimally adequate. It omits any hint of the return payload or pagination-free single-resource semantics that an agent might want before calling.

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%, including the grant_id override behavior, so the schema already carries the parameter burden. The description adds nothing beyond restating the id-based lookup, which is the expected baseline when the schema is complete.

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

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

States a specific verb and resource ('Get a single email message by id'), which is enough to distinguish it from the sibling list_messages. It does not explicitly name that sibling, but the singular 'single message by id' framing makes the distinction apparent.

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 'by id' — the agent can infer this is for retrieval when a message id is known, versus nylas_list_messages for discovery. There is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the account scoping constraint and the v3 endpoint path, but says nothing about pagination behavior or result shape beyond what the schema's page_token/limit already imply.

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 purpose and followed by the endpoint reference. The raw HTTP path is mildly redundant for an agent but is short and can aid debugging.

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

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

For a simple read-only list tool with full schema coverage, an explicit readOnlyHint, and no output schema requiring explanation, the description covers scope, purpose, and sibling relevance adequately. Pagination mechanics are left entirely to the schema, which is the only real 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 limit, grant_id, and page_token are all documented in the schema itself. The description only implies the account-scoping semantics of grant_id ('for the connected account') and adds no format or usage detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('List calendars') scoped to the connected account, and adds a useful cross-reference that each result carries a calendar_id used by the events tools. It does not explicitly contrast itself with siblings like nylas_list_events or nylas_get_calendar, but the purpose 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?

The clause '(each has a calendar_id used by the events tools)' implicitly signals that this tool is a prerequisite for the events tools, which is helpful context. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative (e.g., get_calendar for a single calendar), so usage is only 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 REST route and the grant-scoping behavior, but says nothing about pagination semantics, default/max page size, or result ordering for a list operation.

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 primary purpose; the endpoint reference is compact and useful for API-aware agents, though it is close to redundant with the tool name.

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 should at least hint at return shape and pagination behavior, since page_token/limit are exposed. The grant-scoping note is helpful, but pagination and default limit behavior are left entirely unaddressed.

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

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

Schema description coverage is 100%, so all five parameters (email, limit, grant_id, page_token, phone_number) are already documented in the schema. The description only echoes the two filter parameters and adds no format or interaction detail beyond the schema.

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

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

States a specific verb and resource ('List contacts for the connected account') plus the optional filtering scope, which is more than a restatement of the title. It does not explicitly differentiate from the closest sibling, nylas_get_contact, which retrieves a single contact.

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 mention of 'optional email/phone filters' implies when the tool is useful, but there is no explicit guidance on when to prefer it over nylas_get_contact, nor any note about paginating through results. Usage is inferable but not 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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds the REST mapping (GET /v3/grants/{grant_id}/drafts) which confirms a non-mutating versioned read, but says nothing about pagination behavior, result ordering, or rate limits.

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

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

Two short sentences with the purpose front-loaded and no filler. The endpoint sentence is marginally redundant for an agent but is compact and conveys API versioning; a slightly lower score reflects that it earns its place less than the first sentence.

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

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

A simple paginated read whose safety profile is covered by annotations and whose three parameters are fully described in the schema. The only real gap is that the response shape and next_cursor pagination semantics are not surfaced in the description, though page_token's schema text partly covers 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 100%, so limit, grant_id, and page_token are all fully documented in the schema itself. The description adds no syntax, format, or defaulting detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List draft emails') plus the scoping qualifier ('for the connected account'), which implicitly separates it from nylas_list_messages and nylas_create_draft. It never names those siblings explicitly, so an agent distinguishes them only by 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?

Usage is only implied by the verb and scope — there is no statement of when to prefer this over nylas_list_messages or how to handle a missing grant_id. No exclusions, prerequisites, or alternative selection guidance are provided.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds the Nylas v3 route and the note that calendar_id is sent as a query param, confirming a plain GET semantically, but says nothing about pagination behavior, default limits, or result ordering. Marginal added value over the annotation.

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

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

Two short, front-loaded sentences with no filler; the core action leads and the implementation note follows. The endpoint sentence is slightly marginal but very brief.

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 list tool with no output schema, the description does not explain the return shape or pagination flow (page_token consuming next_cursor), leaving the agent to infer behavior. It is adequate but leaves real gaps around paging and time-range filtering.

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

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

Schema description coverage is 100%, so all seven parameters (start, end, limit, page_token, show_cancelled, grant_id, calendar_id) are already documented in the schema. The description only restates the calendar_id requirement, adding no format or interaction detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('List calendar events'), which is clearly distinct from the singular-read sibling nylas_get_event and the write sibling nylas_create_event. It doesn't explicitly name an alternative, but the list/get distinction is unambiguous from the name and description.

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 notes that calendar_id is required, which is a prerequisite, but gives no guidance on when to use this tool versus nylas_get_event, nylas_list_calendars, or how it relates to filtering by time range. No when-not or alternative routing is provided.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds that 'folders/labels' are the same concept across providers and cites the underlying endpoint, which is useful context, but it says nothing about pagination, ordering, or what an empty result means.

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

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

Two short sentences with the purpose front-loaded and the endpoint detail second; nothing is wasted and there is no filler.

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

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

For a simple read-only list tool with fully documented parameters and no output schema, the definition covers what an agent needs to invoke it. Minor gap: no description of the result shape or how limit interacts with paging, but that is not required given the safety annotations.

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 grant_id are already documented in the schema itself. The endpoint path reinforces that grant_id is required for the call, but the description adds no semantics beyond what the schema provides, so baseline 3 applies.

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

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

The description states a specific verb and resource ('List mail folders/labels for the connected account'), which clearly separates it from the other list_* siblings such as list_calendars or list_messages. It does not name any sibling explicitly, but the resource itself 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 scoping phrase 'for the connected account', and the schema's grant_id note indicates the account-override behavior. There is no explicit when-to-use/when-not guidance or reference to alternatives, so it stays at minimum-viable.

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 v3 endpoint and the non-grant-scoped nature, but says nothing about pagination behavior, auth requirements, or result volume beyond what the schema implies.

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 clauses, front-loaded with the core action and output meaning before the scoping note. The trailing "Nylas v3: GET /v3/grants" is mildly redundant but compact and useful for verification.

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 no output schema, the description supplies the key output fact (each entry carries a grant_id) and the scoping caveat. Only pagination/volume behavior is left implicit, which the limit/offset schema largely covers.

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% for both limit and offset, so the schema fully documents the parameters. The description adds no syntax, default, or range guidance beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb (List) and resource (connected accounts/grants) and clarifies the output includes a grant_id used to scope other tools. This clearly separates it from the sibling nylas_get_grant, which fetches a single grant, 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?

"Not grant-scoped" is an explicit condition telling the agent this tool does not need a grant_id, unlike most sibling tools. It does not name get_grant as the single-grant alternative, but the selection context is unambiguous.

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

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

The readOnlyHint=true annotation already declares the safe, non-destructive profile, so the bar is lower. The description adds only the API route (GET /v3/grants/{grant_id}/messages), which is mildly useful but discloses nothing about pagination behavior, result volume, or rate limits.

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

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

Two compact sentences with the core capability front-loaded before the API route. No filler, though the endpoint reference is of marginal value to an agent that already has 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 10-parameter read-only list tool, the definition is adequate: safety is covered by annotations and every parameter by the schema. It stops short of noting return shape or that page_token drives pagination, which would round it out since no output schema exists.

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

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

Schema description coverage is 100%, so all 10 parameters (from, to, subject, unread, starred, page_token, etc.) are already documented in the schema. The description's "optional filters" adds no syntax or semantics beyond that, making the baseline 3 the correct call.

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 ("email messages") scoped to the connected account, so an agent can distinguish it from the singular nylas_get_message. Differentiation from siblings is implied by "List" rather than made explicit, keeping it 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?

"with optional filters" describes capability but gives no when-to-use guidance, no exclusions, and never names alternatives like nylas_get_message (single message) or nylas_list_drafts. The agent must infer the list-vs-fetch boundary from the tool 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 destructiveHint=true, and the description reinforces this by stressing that an actual message is dispatched. That repetition is useful emphasis but adds little new behavioral detail — no mention of error cases, whether the send is undoable, or what happens with the reply_to_message_id threading.

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, irreversibility front-loaded before the endpoint detail. 'SENDS a real email' and 'dispatches an actual message' are somewhat redundant, costing a little tightness.

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

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

For a high-stakes mutation with no output schema and fully documented parameters, the description covers the essential traits: it is a live send, tied to a connected grant. Remaining gaps (threading behavior, failure modes) are minor given the schema's completeness.

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

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

Schema description coverage is 100%, so all seven parameters (to, cc, bcc, subject, body, grant_id, reply_to_message_id) are already documented in the schema. The description adds no additional parameter meaning, which matches the baseline of 3 when the schema carries the load.

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

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

States a specific verb and resource ('SENDS a real email via the connected account') and reinforces it with 'dispatches an actual message', which implicitly separates it from the draft-creating sibling. It does not name nylas_create_draft explicitly, so the differentiation is inferable rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use guidance. An agent must infer from 'real email' that this is the irreversible-send path versus nylas_create_draft, but the description never says so directly or names preconditions.

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