product_create_artifact

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

Annotations already declare this as a non-read-only, open-world, non-destructive creation tool. The description adds useful behavioral context about required fields and type-dependent parameters. It does not mention permissions or side effects, but with annotations covering the safety profile and an output schema present, this is adequate.

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?

Four tightly written sentences, front-loaded with the core action and followed by conditional requirements. Every sentence adds relevant guidance with no 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 output schema and annotations, the description covers the main creation requirements and routes agents to get_artifact_schema for type-specific fields. The main remaining gap is that the 'fields' parameter format is not described, but the schema pointer mitigates this for a tool with eleven artifact types.

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 description coverage is 0%, so the description must compensate. It explains conditional roles for parent_id and release_id, and hints at fields content via required name/description and the get_artifact_schema pointer. However, it leaves the core 'fields' array structure and product_id semantics unexplained, so compensation is only partial.

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 states a specific verb and resource: 'Create artifacts in a Spira product.' This clearly distinguishes it from siblings like product_update_artifact and product_get_artifact. It does not explicitly contrast with create_association or create_comment, but the resource and action are 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?

It provides clear conditional guidance: name and description are required for most types, sub-artifacts require parent_id, builds require release_id, and optional fields are discoverable via get_artifact_schema. It lacks an explicit 'use this instead of update_artifact' statement, but routing to the schema tool is a strong usage signal.

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