project_add_resource

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

With no annotations, the description carries full burden. It discloses key behaviors: copying source, creating directories if missing, appending/updating the media entry, supporting base64/data URIs for bitmaps, routing through the design tier when prep_target is set, and returning the updated media list and written file. This is thorough and transparent.

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 efficiently structured, front-loading the primary purpose in the first sentence. Subsequent sentences add necessary detail about copying, registration, and edge cases. It's slightly long but every sentence contributes valuable information, so it's appropriately concise.

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 tool with 5 parameters, no annotations, and no output schema, the description is complete. It explains the action, all parameters, behavioral nuances, and return values (updated media list and written file). There are no obvious gaps in understanding what the tool does.

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 resource_type values ('bitmap' | 'font' | 'raw'), defines prep_target with examples ('emery', 'menu-icon'), clarifies that source can be base64/data URI for bitmaps, and meaningful context for dir and name. This fully compensates for the lack of schema descriptions.

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 clearly states the tool's action with a specific verb and resource: 'Add a resource to a project and register it in package.json.' It further details that it copies source into resources/ and updates the media list, distinguishing it from sibling tools like image_prep or project_set_meta.

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 clear context: you use this tool to add resources to a project, and it explains optional preprocessing via prep_target. It does not explicitly mention alternatives or when-not-to-use, but the behavior is clear enough for an agent to infer appropriate usage.

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