prepare_reference_asset

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds a key behavioral trait: the tool rejects direct calls unless preceded by run_skill. It also clarifies the project-scoped nature and that it operates on existing assets. This goes beyond what annotations convey, though it leaves unclear what happens on success or if there are side effects.

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?

Two sentences, each earning its place: the first states the core function, the second covers the critical prerequisite and rejection condition. No filler or redundancy.

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 leaves significant gaps: no output schema, no explanation of what 'reference metadata' entails, and no guidance on how to populate the seven parameters (only primaryAssetId is documented in the schema). The run_skill prerequisite is critical but not sufficient for confident invocation.

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 only 14% (only primaryAssetId is described). The description does not compensate for the other six parameters—traits, displayName, negativePrompt, promptFragment, sourceAssetIds, and type—beyond the vague notion of 'existing project assets.' It provides no additional meaning for most parameters.

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 uses a specific verb+resource phrase: 'Create reusable project-scoped reference metadata from existing project assets.' This clearly distinguishes the tool from siblings like generate_image or write_free_doc, and the name 'prepare_reference_asset' aligns with the described function.

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 provides explicit context: 'Call run_skill first' and states that direct calls without the active skill grant/run descriptor are rejected. This tells the agent when and how to invoke the tool, though it does not mention alternatives or exclusions beyond this prerequisite.

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