create_shopping_list

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

No annotations are provided, so the description carries the burden. It discloses that authentication is required and that it returns created list details. However, it does not mention potential side effects (e.g., whether it overwrites existing lists, rate limits, or error conditions). For a creation tool, this is adequate but not rich; it could state that it does not modify existing lists or require specific permissions beyond 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 concise, two sentences, and front-loaded with the primary action. It includes essential return information and authentication requirement without unnecessary fluff. Every sentence adds value.

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?

Given the tool's simplicity (one parameter, no output schema), the description is fairly complete. It explains the return details and authentication requirement. However, it could mention error scenarios or prerequisites (e.g., session validity) more explicitly, but for a simple creation tool, it is sufficient. The lack of output schema is compensated by listing the return fields.

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 schema already provides 100% coverage for the single parameter 'title' with a clear description. The tool description adds minimal extra meaning beyond restating that it accepts a title. Since schema coverage is high, baseline 3 is appropriate; the description does not add syntax or format details beyond what the schema provides.

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 creates a new shopping list (memo-list type) for the authenticated user on Carrefour France, specifying the resource and action. It distinguishes from siblings like get_shopping_lists and get_shopping_list by focusing on creation, and mentions the return details (ID, type, slug, item count, last updated date, EANs).

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 when the user wants to create a new shopping list, and notes the requirement of an authenticated Carrefour session. It does not explicitly mention alternatives or when not to use, but the context of sibling tools (e.g., get_shopping_lists) makes the purpose clear. A slight deduction for not explicitly stating exclusions or alternatives.

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