Skip to main content
Glama

proposal_create

Record a falsifiable proposal after creating a candidate version and before testing it, defining targets, mechanism, predicted effect, falsification criterion, and prior attempt.

Instructions

Record a falsifiable proposal for a candidate version before testing it: targets, mechanism, predicted effect, falsification criterion and prior attempt. Use it after version_create and before running and gating the candidate; use proposal_list to read earlier proposals. Checks that targets are editable and cover every changed file, pins the current base as parent and snapshots the improver playbook. Appends to the ledger; runs and adopts nothing. Returns the stored proposal with its new id.

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": {
      "config": "<config>",
      "version": "<version>",
      "proposal": "<proposal>"
    },
    "name": "proposal_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
configYesPath of the scenario YAML file on the server host, absolute or relative to the server's working directory, for example `scenario.yaml`. It selects the workspace; a server started with --config rejects any other path.
versionYesCandidate version, different from the current base: 64-character lowercase SHA-256 version id, as returned by version_create.
proposalYesProposal object with exactly five fields: targets, mechanism, predicted_effect, falsification and prior {attempt, difference}.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.1.9
    • addedInput schema / properties / config / description
      Added value: +"Path of the scenario YAML file on the server host, absolute or relative to the server's working directory, for example `scenario.yaml`. It selects the workspace; a server started with --config rejects any other path."
    • addedInput schema / properties / proposal / description
      Added value: +"Proposal object with exactly five fields: targets, mechanism, predicted_effect, falsification and prior {attempt, difference}."
    • addedInput schema / properties / proposal / properties / falsification / description
      Added value: +"The measured result that would show the proposal is wrong, for example 'net <= 0'."
    • addedInput schema / properties / proposal / properties / mechanism / description
      Added value: +"The general mechanism the change applies, in one or two sentences."
    • addedInput schema / properties / proposal / properties / predicted_effect / description
      Added value: +"Predicted paired net score change on the selection split, in summed per-task score units, for example 3."
    • addedInput schema / properties / proposal / properties / prior / description
      Added value: +"Link to an earlier attempt of the same idea, if any."
    • addedInput schema / properties / proposal / properties / prior / properties / attempt / description
      Added value: +"Id of an earlier proposal this one revisits, or null for a first attempt."
    • addedInput schema / properties / proposal / properties / prior / properties / difference / description
      Added value: +"What differs from the prior attempt, or why this is the first."
    • addedInput schema / properties / proposal / properties / targets / description
      Added value: +"Editable file paths, relative with forward slashes, covering every file the candidate changes, for example [\"prompts/guide.txt\"]."
    • addedInput schema / properties / version / description
      Added value: +"Candidate version, different from the current base: 64-character lowercase SHA-256 version id, as returned by version_create."
  2. First observedv0.1.7

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare a non-read-only, non-destructive, non-idempotent mutation; the description adds real substance: it validates that targets are editable and cover every changed file, pins the current base as parent, snapshots the improver playbook, and appends to the ledger. It also bounds the scope explicitly ('runs and adopts nothing') and states the return value, which annotations cannot convey.

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?

Three sentences, front-loaded with purpose, then sequencing, then side effects and return value. Dense but nearly every clause carries information; the field enumeration in sentence one slightly duplicates the schema, which keeps it from a 5.

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

Completeness5/5

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

For a 3-parameter mutation with a deep nested object and no output schema, the description covers purpose, prerequisites, validation behavior, side effects and the shape of the return value. Nothing an agent needs in order to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so config, version and the nested proposal fields are already fully documented, making 3 the baseline. The description echoes the proposal field list and adds one genuine constraint not spelled out in the schema — that targets must be editable and must cover every changed file — but does not explain config path resolution or the version-vs-base rule beyond what the schema already states.

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

Purpose5/5

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

The description opens with a specific verb and resource ('Record a falsifiable proposal for a candidate version') and enumerates the exact payload (targets, mechanism, predicted effect, falsification criterion, prior attempt). It is unmistakable against sibling proposal_list, which is named as the read-side counterpart.

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

Usage Guidelines5/5

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

It states explicit ordering ('after version_create and before running and gating the candidate') and names the alternative for the read case ('use proposal_list to read earlier proposals'). Both when-to-use and which-sibling-to-pick are stated rather than inferred.

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