list_artifacts

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

With no annotations, the description carries the transparency burden. It makes the read-only behavior clear by using 'List' and 'Browse', and it discloses that artifact content is not returned here by directing content retrieval to get_artifact. It also states the access constraint that agent_id must belong to the session, but it does not mention ordering, pagination, or result limits.

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 well-structured in short labeled sections and every sentence adds value: purpose, trigger conditions, routing to get_artifact, and parameter semantics. There is no filler or repetition.

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?

The description covers purpose, triggers, parameters, and the content/get_artifact distinction, which is strong for a filtered read-only list tool with no output schema. It does not describe the exact return shape or mention grep_artifacts as the alternative when searching artifact contents, but that is a minor gap rather than a critical omission.

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 provides 0% description coverage, but the description's PARAMETERS section fully explains each parameter: session_id as target, agent_id with the session-membership constraint, created_by as an optional creator filter with a natural-language example, and artifact_type with concrete allowed-type examples. This substantially compensates for the empty schema.

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 opens with a clear verb and resource: 'List artifacts in a session.' It also gives concrete artifacts ('work products, analyses, and summaries') and distinguishes itself from get_artifact by explicitly routing content retrieval there.

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 has an explicit 'AUTOMATIC TRIGGERS' section telling an agent exactly when to call it: checking saved work, finding an analysis, or avoiding duplicates before creating a new artifact. It also points to get_artifact when artifact content is needed, giving a clear alternative.

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