Skip to main content
Glama
Sign In
AIWorkhub

AIWorkhub

by shrec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

aiworkhub_task_codex_handoff

Read-only

Generate a read-only Codex handoff report for review-queue tasks, summarizing IDs, allowed writes, validation commands, risks, and scoped stage/finalize steps without mutating the queue.

Instructions

READ-ONLY: Codex-ready HANDOFF report for review-queue tasks.

Use this for the handoff as JSON; use aiworkhub_task_codex_handoff_markdown for the same report rendered as Markdown.

For each task waiting on Codex review, summarizes task_id, runner, topic, allowed_writes, validation commands, derived risks, commit-hygiene status, and a scoped stage/finalize command list — WITHOUT mutating the parent task queue.

FROZEN READ-ONLY CONTRACT — no write-gate toggle, no mutation parameters. Never calls taskctl done/review/start/auto-pickup/add-card. Never mutates queue or audit state. Never launches agents or processes. Writes remain default-off regardless of input values.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "aiworkhub_task_codex_handoff"
  }
}

Input Schema

NameRequiredDescriptionDefault
task_idsNoOnly report these task ids; omit for every task waiting in the review queue.
batch_labelNoFree-text label echoed back as batch_label in the reply; it does not filter anything.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.12.67
    • addedInput schema / properties / batch_label / description
      Added value: +"Free-text label echoed back as batch_label in the reply; it does not filter anything."
    • addedInput schema / properties / task_ids / description
      Added value: +"Only report these task ids; omit for every task waiting in the review queue."
  2. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only say readOnlyHint=true and openWorldHint=false; the description goes much further with a 'FROZEN READ-ONLY CONTRACT' that lists exactly which imperative commands it never calls (done/review/start/auto-pickup/add-card), confirms it never mutates queue or audit state, never launches agents or processes, and that writes stay default-off regardless of input. That is precisely the kind of side-effect and safety detail annotations cannot carry.

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?

The read-only guarantee is front-loaded and the JSON-vs-Markdown routing follows immediately, which is the right order. The block of prohibition sentences is somewhat repetitive (three separate 'never mutates/never calls/never launches' clauses overlap), costing a bit of tightness.

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?

An output schema exists, so return shape need not be described, yet the description still outlines the per-task content. With only two optional well-documented parameters and a fully elaborated safety contract, there is nothing an agent needs in order to invoke this correctly that 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%, and the schema already explains that task_ids narrows the report and that batch_label is echoed without filtering. The description adds no additional parameter syntax, defaults, or format details, so the schema does the heavy lifting and a baseline 3 is appropriate.

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?

States a specific verb-and-resource ('Codex-ready HANDOFF report for review-queue tasks') and enumerates the exact payload fields (task_id, runner, allowed_writes, validation commands, risks, commit hygiene, stage/finalize commands). It also names the sibling aiworkhub_task_codex_handoff_markdown as the same report in a different format, so the agent can distinguish them without opening schemas.

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?

Gives an explicit format-selection rule: use this tool for JSON, use aiworkhub_task_codex_handoff_markdown for the rendered Markdown version. Scope is implied by 'tasks waiting on Codex review' and the task_ids parameter, but it never states when to prefer this over siblings such as aiworkhub_task_review_queue or aiworkhub_review_packet, so no explicit exclusions are present.

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