Skip to main content
Glama

penny_edit

DestructiveIdempotent

When the user corrects something on file, or a task, tracker, skill, or block needs to change, edit the existing item rather than writing a duplicate. Modify what already exists; entityType uses the same taxonomy as penny_write (see ladder). Notes: updates[] patch/replace, max100. Tasks: taskId; cancel via status:canceled, never Trash. Profile: blockName + content upsert; memory_policy and persona hold standing instructions. When the user tells you what to save, skip, check, or surface, update their memory_policy block in the same turn as a general rule in their words. Skill redefinition prepares a preview, not a save; wait for user approval before op:apply with proposalId. cancel discards; undo recovers the prior version if no later edit exists. skills/history supplies historyId; restore_revision with skillId/historyId/expectedUpdatedAt previews recovery. restore with skillId recovers deleted skills disabled. No invocation waiting period. Trackers: trackerId + sparse name/description/unit/kind/targetSpec/archived; retire by archiving, no delete. Private trackers only; workspace trackers unsupported. Rhythms: full manifest. skill_run/rhythm_run: complete runId + status. Projects: projectId + expectedRevision + operationId + sparse patch; reread and reconcile on conflict. restore_revision restores fields/resourceIds from historyId as a new revision. Tracker entries: trackerId + entryId + expectedUpdatedAt + full payload. restore un-trashes note/tracker_entry ids or Project projectId. When the user asks to go off the record, entityType: "session" + record: "off" + the sessionId from <mypenny-session> stops this session's transcript reaching Penny and drops what wasn't processed yet; it can't be undone for the session.

Input Schema

NameRequiredDescriptionDefault
opNorestore: un-trash notes/tracker entries by ids.
idsNorestore: IDs to un-trash; max 100.
goalNorhythm: required run instructions; skill uses instructions instead.
kindNotracker: habit|metric|goal|log|status|custom.
nameNoarea/project/tracker: name. entityType:"skill": previews replacement; rhythm: upserts.
unitNotracker: unit of measure.
actorNotask/area/project/heading: actor (me|agent) recorded in activity ledger.
notesNotask/area/project: markdown body.
orderNotask/area/project/heading: sort order.
orgIdNoarea/project/heading: required container ID to update.
ownerNotask: assignee.
patchNoProject patch: full schema on penny_write.
runIdNoskill_run/rhythm_run: required run ID to complete.
scopeNoProfile: global|workspace. Projects: private; workspace requires workspaceId.
titleNotask/heading: title/label.
areaIdNoproject: parent area.
fieldsNoRestore selection: field names or step:<stepId>; fields/resourceIds required.
recordNoentityType:"session" (required) — "off". One-way: there is no way back on for the session.
statusNotask: open|in_progress|done|canceled. Repeating completion returns nextTaskId: act on that new occurrence; the completed ID rejects further status writes. skill_run/rhythm_run: done|error|skipped.
taskIdNotask: ID to update.
whenAtNotask/project: schedule date (ms epoch).
contentNoprofile: required new block content.
deliverNoentityType:"skill": required with trigger; rhythm: required. Omit for on-demand. Shape: penny_write.
enabledNoskill: false pauses due signals, true resumes; requires skillId. Penny does not run skills.
entryIdNo
payloadNo
postureNoentityType:"skill" with trigger, or rhythm: read|propose|act.
skillIdNoskill: ID required with enabled to pause/resume.
triggerNoentityType:"skill": optional; rhythm: required. Omit to return to on-demand. Penny does not run it; connected agents receive due signals. Shape: penny_write. ALWAYS set IANA timezone; default UTC.
updatesNonote: patch or supersede up to 100 existing notes.
archivedNoArea/project/tracker: archive; false reactivates. Tracker definitions retire only this way.
deadlineNotask/project: hard due date (ms epoch).
snapshotNoskill restore_revision: history side; default before. after recovers an undone change.
agentNoteNo
blockNameNoprofile: required block to upsert.
dependsOnNotask: full prerequisite taskId set; replaces all.
historyIdNorestore_revision: Project/skill history ID. Skill restore previews; requires skillId and expectedUpdatedAt.
linkNotesNotask: note IDs to link.
projectIdNoheading: required parent Project.
sessionIdNoentityType:"session" — the transcript session to take off the record, from <mypenny-session>; omit when the host gives none.
trackerIdNotracker: required ID to update; only supplied fields change.
entityTypeYesItem type.
proposalIdNoReturned skill proposal. apply commits after user review; cancel discards; undo restores the previous version only if no later edit exists.
provenanceNorhythm_run: accountability summary (IDs/labels, never full content).
recordedAtNo
recurrenceNotask: set/change recurrence. clearFields:["recurrence"] ends the series, making the task one-off and preserving completed history. Target currentOccurrenceId, not a stale/completed ID.
targetSpecNotracker: replaces the whole target spec; shape as penny_write.
whenBucketNotask/project: undated bucket; mutually exclusive with whenAt.
clearFieldsNotask: optional fields to unset.
descriptionNoentityType:"skill"/rhythm: required use-when description. tracker: meaning; log trackers must document payload shape.
operationIdNoProject receipt key; identical retries only.
resourceIdsNoRestore selected links.
taskUpdatesNotask: edits, each {taskId, ...task fields} except card. All are checked first; one bad item saves none.
instructionsNoskill: required saved know-how; replaces rhythm goal.
retrievalPlanNoentityType:"skill"/rhythm: optional deterministic steps for a bounded tier.
expectedRevisionNoProject revision from Brief; reconcile conflicts.
expectedUpdatedAtNoSource version from read.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / entityType / enum
      Previous value: -[
      -  "profile",
      -  "task",
      -  "area",
      -  "project",
      -  "heading",
      -  "tracker",
      -  "rhythm",
      -  "rhythm_run",
      -  "skill",
      -  "skill_run",
      -  "note",
      -  "tracker_entry"
      -]New value: +[
      +  "profile",
      +  "task",
      +  "area",
      +  "project",
      +  "heading",
      +  "tracker",
      +  "rhythm",
      +  "rhythm_run",
      +  "skill",
      +  "skill_run",
      +  "note",
      +  "tracker_entry",
      +  "session"
      +]
    • addedInput schema / properties / record
      Added value: +{
      +  "description": "entityType:\"session\" (required) — \"off\". One-way: there is no way back on for the session.",
      +  "enum": [
      +    "off"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / sessionId
      Added value: +{
      +  "description": "entityType:\"session\" — the transcript session to take off the record, from <mypenny-session>; omit when the host gives none.",
      +  "type": "string"
      +}
    • changedInput schema / properties / taskId / description
      Previous value: -"task: required ID to update."New value: +"task: ID to update."
    • addedInput schema / properties / taskUpdates
      Added value: +{
      +  "description": "task: edits, each {taskId, ...task fields} except card. All are checked first; one bad item saves none.",
      +  "items": {
      +    "type": "object"
      +  },
      +  "maxItems": 100,
      +  "type": "array"
      +}
  2. Changed42 schema fields changed
    • changedInput schema / properties / actor / description
      Previous value: -"entityType:\"task\"/\"area\"/\"project\"/\"heading\" — who took the action (me|agent), written to the activity ledger."New value: +"task/area/project/heading: actor (me|agent) recorded in activity ledger."
    • changedInput schema / properties / areaId / description
      Previous value: -"entityType:\"project\" — the area the project belongs to."New value: +"project: parent area."
    • changedInput schema / properties / blockName / description
      Previous value: -"entityType:\"profile\" (required) — the profile block to upsert."New value: +"profile: required block to upsert."
    • changedInput schema / properties / clearFields / description
      Previous value: -"entityType:\"task\" — names of optional fields to UNSET on the task."New value: +"task: optional fields to unset."
    • changedInput schema / properties / content / description
      Previous value: -"entityType:\"profile\" (required) — the new block content."New value: +"profile: required new block content."
    • changedInput schema / properties / deadline / description
      Previous value: -"entityType:\"task\"/\"project\" — hard due date (ms epoch)."New value: +"task/project: hard due date (ms epoch)."
    • changedInput schema / properties / deliver / description
      Previous value: -"entityType:\"skill\": required with trigger (also rhythm); omit for on-demand. See penny_write for shape."New value: +"entityType:\"skill\": required with trigger; rhythm: required. Omit for on-demand. Shape: penny_write."
    • changedInput schema / properties / dependsOn / description
      Previous value: -"entityType:\"task\" — full replacement set of taskIds that must complete first."New value: +"task: full prerequisite taskId set; replaces all."
    • changedInput schema / properties / description / description
      Previous value: -"entityType:\"skill\": REQUIRED use-when description; also rhythm. tracker: meaning; log trackers must document payload shape."New value: +"entityType:\"skill\"/rhythm: required use-when description. tracker: meaning; log trackers must document payload shape."
    • changedInput schema / properties / enabled / description
      Previous value: -"entityType:\"skill\": false pauses due signals, true resumes; requires skillId. Penny does not run skills."New value: +"skill: false pauses due signals, true resumes; requires skillId. Penny does not run skills."
    • changedInput schema / properties / expectedRevision / description
      Previous value: -"Project edit revision from Brief; reconcile conflicts."New value: +"Project revision from Brief; reconcile conflicts."
    • changedInput schema / properties / expectedUpdatedAt / description
      Previous value: -"Source version from the read."New value: +"Source version from read."
    • changedInput schema / properties / goal / description
      Previous value: -"entityType:\"rhythm\" (required) — what the run should do. On entityType:\"skill\" this is `instructions`."New value: +"rhythm: required run instructions; skill uses instructions instead."
    • changedInput schema / properties / historyId / description
      Previous value: -"restore_revision: Project history item or skill history item. Skill restoration prepares a preview; requires skillId and expectedUpdatedAt."New value: +"restore_revision: Project/skill history ID. Skill restore previews; requires skillId and expectedUpdatedAt."
    • changedInput schema / properties / ids / description
      Previous value: -"op:\"restore\" — ids to un-trash (max 100)."New value: +"restore: IDs to un-trash; max 100."
    • changedInput schema / properties / instructions / description
      Previous value: -"entityType:\"skill\" (required) — the saved know-how (generalizes the rhythm \"goal\")."New value: +"skill: required saved know-how; replaces rhythm goal."
    • changedInput schema / properties / kind / description
      Previous value: -"entityType:\"tracker\" — habit | metric | goal | log | status | custom."New value: +"tracker: habit|metric|goal|log|status|custom."
    • changedInput schema / properties / linkNotes / description
      Previous value: -"entityType:\"task\" — note ids to link to this task."New value: +"task: note IDs to link."
    • changedInput schema / properties / name / description
      Previous value: -"Area/project/tracker name; entityType:\"skill\" names prepare a preview of the replacement (rhythm names upsert)."New value: +"area/project/tracker: name. entityType:\"skill\": previews replacement; rhythm: upserts."
    • changedInput schema / properties / notes / description
      Previous value: -"entityType:\"task\"/\"area\"/\"project\" — markdown body."New value: +"task/area/project: markdown body."
    • changedInput schema / properties / op / description
      Previous value: -"op:\"restore\" un-trashes notes or tracker entries by `ids`."New value: +"restore: un-trash notes/tracker entries by ids."
    • changedInput schema / properties / order / description
      Previous value: -"entityType:\"task\"/\"area\"/\"project\"/\"heading\" — sort order."New value: +"task/area/project/heading: sort order."
    • changedInput schema / properties / orgId / description
      Previous value: -"entityType:\"area\"/\"project\"/\"heading\" (required) — the container to update."New value: +"area/project/heading: required container ID to update."
    • changedInput schema / properties / owner / description
      Previous value: -"entityType:\"task\" — assignee."New value: +"task: assignee."
    • changedInput schema / properties / posture / description
      Previous value: -"entityType:\"skill\" with a `trigger` set (or legacy \"rhythm\") — read | propose | act."New value: +"entityType:\"skill\" with trigger, or rhythm: read|propose|act."
    • changedInput schema / properties / projectId / description
      Previous value: -"entityType:\"heading\" (required) — the project the heading belongs to."New value: +"heading: required parent Project."
    • changedInput schema / properties / proposalId / description
      Previous value: -"Skill change proposal returned by an edit. op:apply commits after user review; cancel discards; undo restores the previous version if no later edit exists."New value: +"Returned skill proposal. apply commits after user review; cancel discards; undo restores the previous version only if no later edit exists."
    • changedInput schema / properties / provenance / description
      Previous value: -"entityType:\"rhythm_run\" — accountability summary of what the run did (ids/labels, never full content)."New value: +"rhythm_run: accountability summary (IDs/labels, never full content)."
    • changedInput schema / properties / retrievalPlan / description
      Previous value: -"entityType:\"skill\" (or legacy \"rhythm\") — OPTIONAL deterministic steps for a bounded tier."New value: +"entityType:\"skill\"/rhythm: optional deterministic steps for a bounded tier."
    • changedInput schema / properties / runId / description
      Previous value: -"entityType:\"skill_run\" (required) — the run to complete; same field on the legacy \"rhythm_run\"."New value: +"skill_run/rhythm_run: required run ID to complete."
    • changedInput schema / properties / skillId / description
      Previous value: -"entityType:\"skill\" pause/resume — the skill id (required with enabled)."New value: +"skill: ID required with enabled to pause/resume."
    • changedInput schema / properties / snapshot / description
      Previous value: -"Skill restore_revision: which side of the history entry to restore (default before). Select after to recover a change that was undone."New value: +"skill restore_revision: history side; default before. after recovers an undone change."
    • changedInput schema / properties / taskId / description
      Previous value: -"entityType:\"task\" (required) — the task to update."New value: +"task: required ID to update."
    • changedInput schema / properties / title / description
      Previous value: -"entityType:\"task\"/\"heading\" — the title/label."New value: +"task/heading: title/label."
    • changedInput schema / properties / trackerId / description
      Previous value: -"entityType:\"tracker\" (required) — the tracker to update. Only the fields you pass are patched — omit any you don't want to change."New value: +"tracker: required ID to update; only supplied fields change."
    • changedInput schema / properties / trigger / description
      Previous value: -"entityType:\"skill\": optional (required for rhythm). Omit to return to on-demand. Penny does not run it; the connected agent receives due signals. See penny_write for shape; ALWAYS set IANA timezone, default UTC."New value: +"entityType:\"skill\": optional; rhythm: required. Omit to return to on-demand. Penny does not run it; connected agents receive due signals. Shape: penny_write. ALWAYS set IANA timezone; default UTC."
    • changedInput schema / properties / unit / description
      Previous value: -"entityType:\"tracker\" — unit of measure."New value: +"tracker: unit of measure."
    • changedInput schema / properties / updates / description
      Previous value: -"entityType:\"note\" — patch or supersede existing notes (up to 100)."New value: +"note: patch or supersede up to 100 existing notes."
    • changedInput schema / properties / updates / items / properties / content / description
      Previous value: -"Required when mode is \"patch\"."New value: +"Required for patch."
    • changedInput schema / properties / updates / items / properties / supersededBy / description
      Previous value: -"Required when mode is \"replace\" — the id of the note that replaces this one."New value: +"replace: required replacement note ID."
    • changedInput schema / properties / whenAt / description
      Previous value: -"entityType:\"task\"/\"project\" — schedule date (ms epoch)."New value: +"task/project: schedule date (ms epoch)."
    • changedInput schema / properties / whenBucket / description
      Previous value: -"entityType:\"task\"/\"project\" — undated bucket; mutually exclusive with whenAt."New value: +"task/project: undated bucket; mutually exclusive with whenAt."
  3. Changed2 schema fields changed
    • changedInput schema / properties / enabled / description
      Previous value: -"entityType:\"skill\": false pauses due signals, true resumes; requires skillId. MyPenny does not run skills."New value: +"entityType:\"skill\": false pauses due signals, true resumes; requires skillId. Penny does not run skills."
    • changedInput schema / properties / trigger / description
      Previous value: -"entityType:\"skill\": optional (required for rhythm). Omit to return to on-demand. MyPenny does not run it; the connected agent receives due signals. See penny_write for shape; ALWAYS set IANA timezone, default UTC."New value: +"entityType:\"skill\": optional (required for rhythm). Omit to return to on-demand. Penny does not run it; the connected agent receives due signals. See penny_write for shape; ALWAYS set IANA timezone, default UTC."
  4. Changed1 schema field changed
    • changedInput schema / properties / recurrence / description
      Previous value: -"entityType:\"task\" — makes the task repeat, or (on an existing repeating task) changes its schedule. Setting `clearFields: [\"recurrence\"]` ENDS the series (task becomes a one-off; completed occurrences stay as history) but must target `currentOccurrenceId`, not a stale/completed id."New value: +"task: set/change recurrence. clearFields:[\"recurrence\"] ends the series, making the task one-off and preserving completed history. Target currentOccurrenceId, not a stale/completed ID."
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already mark the tool destructive and idempotent, and the description adds substantial context beyond them: skill redefinition previews require approval, cancel discards, undo only works if no later edit exists, project conflicts require rereading, private trackers only, and going off-record cannot be undone. These details materially improve safe invocation and do not contradict the annotations.

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 and the information density is high, which suits a 57-parameter tool. However, the body is a dense semicolon-separated run-on with cryptic fragments like 'Rhythms: full manifest' and 'No invocation waiting period', making it harder to scan than it needs to be.

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 highly complex destructive tool with no output schema, it covers the major entity types, operation modes, approval and undo behavior, conflict reconciliation, and session privacy semantics. It is strong overall, though some entity types such as areas and headings are left mostly to the schema, and return/error expectations are not described.

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 description coverage is 93%, so the baseline is 3, but the description adds useful entity-specific recipes such as updates[] patch/replace max 100, profile blockName + content upsert, skill preview via proposalId, and tracker entries requiring trackerId + entryId + expectedUpdatedAt + full payload. Some params remain vague or externally referenced, such as 'see ladder', and a few fields like agentNote and recordedAt are not clarified.

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: edit an existing item rather than writing a duplicate. It distinguishes itself from penny_write by naming the shared taxonomy, so an agent can tell this is the mutation/update path rather than creation.

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 explicitly says when to edit instead of duplicating, then gives entity-specific triggers for tasks, trackers, skills, profiles, projects, rhythms, and sessions. It also names operation alternatives such as cancel, apply, undo, and restore_revision, so the agent has clear routing guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources