Paginated list of gifts on the account, with optional status and date filters. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of gifts to return, 1 to 100. Defaults to 50. | |
| since | No | Only return gifts created at or after this ISO 8601 timestamp. | |
| cursor | No | Opaque pagination cursor from a previous list_gifts response. | |
| status | No | Only return gifts in this status, for example shipped, delivered, or cancelled. |
Changes observed during successful MCP inspections.
Input schema / properties / cursor / descriptionAdded value: +"Opaque pagination cursor from a previous list_gifts response."Input schema / properties / limit / descriptionAdded value: +"Maximum number of gifts to return, 1 to 100. Defaults to 50."Input schema / properties / since / descriptionAdded value: +"Only return gifts created at or after this ISO 8601 timestamp."Input schema / properties / status / descriptionAdded value: +"Only return gifts in this status, for example shipped, delivered, or cancelled."Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It states 'Paginated' but doesn't explain pagination mechanism (cursor-based) or return structure. 'Free' is ambiguous. No mention of sorting, rate limits, or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus 'Free.'), wasting no words. However, it could include more structure without sacrificing conciseness, such as a note about cursor-based pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should hint at return format. It does not mention that the response contains a list of gift objects and a cursor for pagination. Also missing are default sorting order and how to use the cursor parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. The description adds 'optional status and date filters' which aligns with schema but provides no new detail beyond the schema's parameter descriptions.
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 clearly states the tool lists gifts on the account with optional filters, using the verb 'list' and resource 'gifts'. It distinguishes from siblings like get_gift (single item) and create_gift.
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 for listing gifts with filters but provides no explicit guidance on when to use this tool vs alternatives or when not to use it. 'Free.' hints at cost but no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.