list_artifacts

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

With no annotations, the description carries the full burden, and it does disclose scope ('in the workspace'), ordering ('newest first'), and the transient nature of the artifacts. However, it says nothing about how results are capped beyond limit, whether older items become unreachable, auth/permission requirements, or failure behavior.

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?

Front-loaded with the core action and scope, followed by a one-sentence rationale for using it. The 'Args:' block is slightly formal for a single parameter but not wasteful.

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?

An output schema exists, so return values need not be explained, and with one optional parameter the surface is small. The description covers what artifacts are, their ordering, and the intended use case, leaving only minor gaps such as total-count or truncation 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?

Schema coverage is 0% (the 'limit' property has only a title and default of 20), so the description must compensate; it does minimally by defining limit as 'Maximum number of artifacts to return.' That is really just a restatement of the parameter name, with no guidance on sensible values or behavior when omitted beyond the schema default.

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 names a specific verb and resource ('List recent temporary artifacts in the workspace') and adds ordering ('newest first'), so the operation is unambiguous. It is plainly distinct from the PDF-oriented siblings, though it does not explicitly contrast itself with any of them (none overlap meaningfully).

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?

It gives a concrete triggering situation: 'Useful when you have lost track of an artifact id from earlier in the conversation, so you can find it again instead of redoing the work.' That is clear when-to-use guidance tied to a real alternative (redoing the work), but it does not state any when-not conditions or name an alternative tool.

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