Skip to main content
Glama
Sign In
AIWorkhub

AIWorkhub

by shrec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

needfix_convert

Converts an accepted NeedFix into a task card and can preview and commit a task plan in one call, refusing invalid or drifted plans.

Instructions

Convert an accepted NeedFix into a task card; task_plan alone commits in one call.

With task_plan and no plan_digest this previews the plan and, only when the preview is convertible with no input refusal, commits it with the digest that preview returned, in the same call. A captured or triaged NeedFix whose task_plan names non-empty allowed_writes is auto-promoted to accepted (reason auto_promoted_by_convert) first. Any refusal returns the preview and commits nothing. plan_digest alone also commits the exact plan its preview signed; a digest this server no longer holds is refused with previewed_plan_unavailable. The digest re-check is unchanged, so NeedFix drift still fails closed.

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": {
      "needfix_id": "<needfix_id>"
    },
    "name": "needfix_convert"
  }
}

Input Schema

NameRequiredDescriptionDefault
task_planNoTask card fields as in needfix_preview_convert. Given without plan_digest, the plan is previewed and committed in one call.
needfix_idYesNeedFix id, e.g. NF-2026-01447.
plan_digestNoplan_digest from the matching needfix_preview_convert; optional when task_plan is given. A digest this server no longer holds is refused.
include_planNoReturn the plan body verbatim instead of a summary of its identity and counts; default false.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.12.94
    • changedInput schema / properties / plan_digest / description
      Previous value: -"plan_digest from the matching needfix_preview_convert; required to commit a new conversion. A digest this server no longer holds is refused."New value: +"plan_digest from the matching needfix_preview_convert; optional when task_plan is given. A digest this server no longer holds is refused."
    • changedInput schema / properties / task_plan / description
      Previous value: -"Task card fields as in needfix_preview_convert; omit to commit the exact plan remembered under plan_digest."New value: +"Task card fields as in needfix_preview_convert. Given without plan_digest, the plan is previewed and committed in one call."
  2. Changed4 schema fields changedv0.12.67
    • addedInput schema / properties / include_plan / description
      Added value: +"Return the plan body verbatim instead of a summary of its identity and counts; default false."
    • addedInput schema / properties / needfix_id / description
      Added value: +"NeedFix id, e.g. NF-2026-01447."
    • addedInput schema / properties / plan_digest / description
      Added value: +"plan_digest from the matching needfix_preview_convert; required to commit a new conversion. A digest this server no longer holds is refused."
    • addedInput schema / properties / task_plan / description
      Added value: +"Task card fields as in needfix_preview_convert; omit to commit the exact plan remembered under plan_digest."
  3. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations only declare this is a non-read-only, non-destructive, closed-world mutation. The description goes well beyond that, disclosing a side effect the annotations do not: a captured or triaged NeedFix with non-empty allowed_writes is auto-promoted to accepted with reason auto_promoted_by_convert. It also documents fail-closed semantics (drift still fails, digest re-check unchanged). It stops short of covering repeat-call idempotency or behavior for NeedFixes in other statuses.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is dense run-on prose with double-backtick markup fragments and nested conditionals ("previews the plan and, only when the preview is convertible with no input refusal, commits it...") that take several reads to parse. Content largely earns its place, but structure could be tightened into discrete mode statements.

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

Completeness4/5

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

For a mutation tool with no output schema, the description covers commits, previews, refusals, side effects, and the include_plan return variant. The remaining gap is that it never describes the shape of a successful commit result (task card identity) beyond the include_plan toggle.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by explaining cross-parameter interaction the schema cannot: task_plan+no digest previews then commits with the returned digest, and plan_digest alone replays the exact signed plan. The only untouched parameter is include_plan, which the schema already documents.

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 opening clause states a specific verb and resource ("Convert an accepted NeedFix into a task card") and immediately adds that giving ``task_plan`` alone commits in a single call, which distinguishes this from the preview-only sibling. An agent can tell what the tool produces without opening the schema.

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

Usage Guidelines4/5

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

The description lays out the three invocation modes clearly: task_plan alone commits, task_plan without plan_digest previews-then-commits, and plan_digest alone commits a previously signed plan. It also states the failure paths (any refusal commits nothing, stale digest refused as ``previewed_plan_unavailable``). What it never says explicitly is when an agent should stop here versus calling needfix_preview_convert first, so the alternative is only implicit.

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

Deploy Server

Other Tools