add_asset

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

No annotations are provided, so the description fully carries the behavioral burden — and it does so thoroughly. It discloses the version-creation side effect, LLM-gating against re-adds of soft-deleted assets, the three distinct outcomes (including auto-restore un-deleting tombstones and similar-verdict rejection saving nothing), and specific 503/502 error modes with retry instructions. This is exemplary behavioral disclosure for a mutation 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 description is long, but every section earns its place: purpose is front-loaded in the opening sentence, outcomes are structurally separated with bold headers and bullets, and the error modes are compressed into a compact list. The density is justified by the tool's genuine complexity (LLM-gated outcomes, restore logic, authoring constraints). It is well-organized and scannable, though not a model of brevity.

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?

For a complex, LLM-gated tool with no annotations and an existing output schema, the description covers everything an agent needs: outcome envelopes (normal create, auto-restore, similar-verdict rejection), error handling with retry guidance, component scoping semantics, caller/backend responsibility split, and the authoring contract for asset quality. The presence of an output schema relieves it from detailing return values, and what it does describe complements rather than duplicates that 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 description coverage is 86%, so the baseline is 3. The description adds real meaning on top: it groups parameters into 'identity-bearing fields (name, description, security_properties, notes)' vs. 'optional component scoping,' and gives component_ids substantive semantics (canonical bridge between trust boundaries and repos, flows boundary context into the reachability graph, multi-instance shape). The authoring contract also enriches the name parameter. However, server_version and security_properties receive no added meaning beyond the schema, capping this at 4.

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?

Opens with 'Add a new asset to a threat model. Creates a new version.' — a specific verb+resource pair that states the primary action and its versioning side effect. It distinguishes from the sibling edit_asset by explicitly routing post-create factor overrides there, and the caller/backend split clarifies that this tool creates the asset while the backend handles factor decomposition.

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?

Explicitly names edit_asset as the alternative for post-create overrides ('Override any factor post-create via edit_asset with a change_reason'), and the authoring contract provides prescriptive guidance on what constitutes an acceptable asset to add (name the data/resource being protected, not a mechanism). Component scoping guidance ('Multi-component is the right shape for multi-instance assets') also clarifies when to add components. It stops short of an explicit when-not-to-use exclusion list, so 4 rather than 5.

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