Skip to main content
Glama
research-workflow-studio

research-workflow-studio

by BorgDiven

rws_usage_save

Idempotent

Reference precise artifacts in a target experiment, including cross-project reuse, while leaving the original producer unchanged.

Instructions

Reference precise artifacts in a target experiment, including cross-project reuse. Original producer remains unchanged.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "requestId": "<requestId>",
      "projectId": "<projectId>",
      "expectedRevision": "<expectedRevision>",
      "experimentRef": "<experimentRef>",
      "artifactRefs": "<artifactRefs>",
      "role": "<role>"
    },
    "name": "rws_usage_save"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNo
roleYes
labelNo
projectIdYes
requestIdYes
artifactRefsYes
experimentRefYes
expectedRevisionYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.4.2
    • changedInput schema / properties / artifactRefs / items / properties / type / enum
      Previous value: -[
      -  "research",
      -  "experiment",
      -  "code",
      -  "run",
      -  "artifact",
      -  "protocol",
      -  "dataset",
      -  "evaluation",
      -  "comparison",
      -  "analysis",
      -  "report",
      -  "conversation",
      -  "proposal",
      -  "usage",
      -  "spec",
      -  "amendment"
      -]New value: +[
      +  "research",
      +  "experiment",
      +  "code",
      +  "run",
      +  "artifact",
      +  "protocol",
      +  "dataset",
      +  "evaluation",
      +  "comparison",
      +  "analysis",
      +  "report",
      +  "conversation",
      +  "proposal",
      +  "usage",
      +  "spec",
      +  "amendment",
      +  "server",
      +  "repository",
      +  "environment",
      +  "operation"
      +]
    • changedInput schema / properties / experimentRef / properties / type / enum
      Previous value: -[
      -  "research",
      -  "experiment",
      -  "code",
      -  "run",
      -  "artifact",
      -  "protocol",
      -  "dataset",
      -  "evaluation",
      -  "comparison",
      -  "analysis",
      -  "report",
      -  "conversation",
      -  "proposal",
      -  "usage",
      -  "spec",
      -  "amendment"
      -]New value: +[
      +  "research",
      +  "experiment",
      +  "code",
      +  "run",
      +  "artifact",
      +  "protocol",
      +  "dataset",
      +  "evaluation",
      +  "comparison",
      +  "analysis",
      +  "report",
      +  "conversation",
      +  "proposal",
      +  "usage",
      +  "spec",
      +  "amendment",
      +  "server",
      +  "repository",
      +  "environment",
      +  "operation"
      +]
  2. First observedv0.3.3

TDQS

C2.9/5.0
Behavior3/5

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

Annotations already declare this is a non-read-only, non-destructive, idempotent, closed-world write, so the safety profile is covered. The description adds genuine value beyond that by clarifying the producer artifact is left unchanged (a reference, not a move or copy). It says nothing about what happens on expectedRevision mismatch, how requestId deduplicates retries, or permission requirements, which matters for a write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no padding, and the core behavior is front-loaded. 'Precise' is mild filler that could be dropped, but the second sentence carries real information about the producer being unchanged.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write tool with 8 parameters, nested reference objects, optimistic-concurrency control, and no output schema, the description is far too thin. An agent still lacks guidance on role values, revision-conflict behavior, retry semantics via requestId, and what the call returns or how to undo it (rws_usage_remove).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 8 parameters, including nested artifactRefs and experimentRef objects, so the description must compensate and largely does not. It implies that refs carry their own project scope (cross-project reuse) and that a target experiment is identified, but says nothing about role, label, expectedRevision, or requestId. Two of the six required parameters are untouched.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete action and resource: referencing artifacts into a target experiment, with the scope extension of cross-project reuse. An agent can infer this creates a usage link rather than mutating the referenced artifact. It stops short of naming the sibling it complements or excludes (rws_usage_remove), and never says explicitly that it writes a 'usage' record, so the tool-name mapping requires a small inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is given, and no alternatives are named despite rws_usage_remove existing as the obvious counterpart. 'Including cross-project reuse' hints at a supported scenario but is not framed as a selection rule, and prerequisites such as needing an existing experiment and the current revision are absent.

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