assets_list

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

No annotations are provided, so the description carries the burden of disclosing the tool's behavior. It states a non-mutating 'List' operation scoped to the personal assets store, which is an important safety signal. It does not mention ordering, return payload, or edge cases, but these are minor for a simple read-only listing tool.

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 descition is a single sentence that leads with the action and resource, then states the key optional behaviors. Every word adds value and there is no redundancy or 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?

Given the low complexity, three optional well-described params, and no output schema, the definition is adequate for an agent to invoke correctly. It could mention response shape, but 'List files' sufficiently implies a list result and the schema covers all calling specifics.

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 input schema already covers all three parameters with detailed descriptions and 100% coverage. The description only restates 'optional prefix filtering and pagination' without adding new semantic detail. The baseline of 3 is appropriate because the schema does the heavy lifting.

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 uses a specific verb and resource: "List files in your personal assets store." It also mentions optional prefix filtering and pagination, which clearly scopes the tool's behavior. The verb 'List' distinguishes it from the sibling tools assets_upload, assets_delete, assets_copy, and assets_head.

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 clearly conveys when to use the tool: whenever you need to enumerate files in the personal assets store, with optional prefix narrowing and pagination. It does not explicitly name alternatives or state when not to use it, so it stops short of full exclusionary guidance.

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