bridge_artifact

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral context: writes are versioned and non-overwriting, and creation has no side effects on skills or routines. This clarifies the tool's safety profile and side-effect scope. It does not mention potential error conditions or what happens on duplicate writes, but it goes beyond the minimal annotation coverage.

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 two sentences with no fluff. The core purpose is front-loaded in the first sentence, and the second adds a critical side-effect clarification. Every word contributes to the agent's understanding.

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 4-parameter tool with no output schema and sparse annotations, the description is incomplete. It omits definitions for 'name', 'project', and 'text', does not describe return values or error behavior (e.g., what happens if the artifact exists), and gives no context on how these parameters relate to other bridge tools. An agent would need additional information to call it correctly in all cases.

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?

The schema has 0% description coverage, so the description must compensate. However, it only clarifies the 'action' parameter (write/read) through the enum and the phrase 'without overwriting'. It does not explain the purpose of 'name', 'project', or 'text', leaving the agent to guess these are artifact identifiers and content. The description adds little value for parameter meaning.

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 a specific verb('Create' or 'read') and a resource ('versioned UTF-8 artifact'), and adds a distinctive property ('without overwriting') that differentiates it from ordinary writes. It also explicitly says what it does not do ('does not install skills or schedule routines'), which helps set it apart from sibling tools like bridge_submit or bridge_steer without needing their schemas.

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 a negative usage hint: artifact creation does not install skills or schedule routines, implying those actions belong to other tools. However, it does not explicitly name alternatives or state concrete conditions for when to use this tool versus a sibling. The guidance is present but implicit, leaving the agent to infer the full decision.

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