Set Model Provenance

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states 'Mutating: bumps the model version' and explains the authority semantics for kind='code' versus other kinds, including that component changes are applied and queued for review. It does not cover permissions or reversibility, but covers the core behavioral traits well.

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 compact and front-loaded: the first sentence states purpose, the second gives timing, and the final paragraph explains the critical kind semantics. Every sentence earns its place, though the inline-code notation adds some density.

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 tool's semantic complexity, the description covers when to call it, what side effects it has, and the authoritative-source distinction between code and other kinds. The presence of an output schema reduces the need to describe return values, and the remaining parameters are covered by the input schema.

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 88%, so the baseline is 3, but the description adds meaningful semantics for kind and commit_sha, explaining that code with commit_sha makes the code authoritative and how reconcile_model measures the model against it. The remaining parameters are already well documented in the 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 specific verb and resource: 'Record where a model's description came from.' It clearly distinguishes the tool from generate_threat_model by noting that provenance_* params can be passed there instead, and it names reconcile_model as the related measurement tool.

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 explicitly states when to call this tool: 'right after generating a model from a repository' and 'again whenever the source changes.' It also names the alternative approach of passing provenance_* params to generate_threat_model, giving the agent a clear decision point.

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