Listings auflisten

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

With no annotations provided, the description carries the full burden. It adds meaningful behavioral details: max 100 results per call due to Etsy limit, pagination via offset, included fields per listing, and default status behavior. It doesn't cover auth or error cases, but the disclosed behavior is solid.

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 concise sentences, front-loaded with the main action, then filters, output fields, and pagination limit. No redundant words or repetition of schema defaults.

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 list tool with no output schema, the description covers the key return fields and pagination. It could be more explicit about which shop is being listed (presumably the authenticated shop) and sorting order, but overall it's sufficiently complete for an agent to understand the tool's behavior.

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 the state parameter has a schema description (33% coverage), so the description must compensate. It explains the status enum values, the default active behavior, and that offset is used for pagination. The limit parameter is implicitly covered by the max 100 results statement, though it isn't explicitly named.

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?

Description uses specific verb 'Listet Listings des Shops auf' (lists shop listings) and clearly specifies the scope: filtered by status. This distinguishes it from siblings like etsy_get_listing (single listing) and etsy_get_listing_inventory, making the purpose 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 description gives clear usage context: it lists listings, defaults to active when no status is given, and explains pagination via offset. It doesn't name alternatives or explicitly state when not to use it, but the context is sufficient for a list endpoint.

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