list_templatesRetrieve all transactional templates from SendGrid, including legacy and dynamic, with optional filtering by generation and page size.
Retrieve all transactional templates (legacy and dynamic)
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Number of templates to return (max 200) | |
| generations | No | Filter by template generation (legacy or dynamic) |
Changes observed during successful MCP inspections.
v1.1.1Input schema / additionalPropertiesRemoved value: -falsev1.0.0Input schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the listing spans both legacy and dynamic generations, but it doesn't disclose pagination behavior or response structure; it also repeats the schema's generation filter values rather than adding new behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and object and contains no filler. It is an appropriately sized definition for a simple list operation.
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 read-only list tool with fully documented optional parameters and safety annotations, the description is sufficient for an agent to select and invoke it. It could mention pagination defaults or the return payload, but those are either implicit in list tools or covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents page_size and generations. The description doesn't add new parameter details; it merely echoes the 'legacy and dynamic' values that the generations schema description already lists, so it meets the baseline but adds no extra meaning.
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 opens with the verb 'Retrieve' and names the resource 'all transactional templates', explicitly scoping to 'legacy and dynamic' generations. This clearly distinguishes it from single-resource siblings like get_template and from mutation tools like create/update/delete_template.
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 the tool's use—call it to list transactional templates—but offers no explicit guidance about when to prefer it over get_template for a specific template or open_template_editor for editing. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.