ShotPulled

Update a grinder

update_grinder

Destructive

Correct a registered grinder: its name, burrs, collar scheme, nominal step, layout, range or notes. Only the keys you send in fields change; send null to clear an optional field (an empty string also clears a text field, but not a number or a closed list). Required fields can be changed but not cleared. fields may be omitted when only reason is sent. setting_scheme, nominal_step and components_spec describe the collar every recorded grind label is read through: call with dry_run first to see which recorded settings would read as a different position, and tell the user before saving. Saving records the change in the grinder's maintenance history; when a locked recipe's setting moves it also opens an unmeasured calibration epoch (set_maintenance_offset resolves it). The collar's current setting is marked assumed when it reads differently, or cleared when the new collar cannot read it, and measured offsets are converted when a click changes worth. Changing direction_convention is a correction: it moves no number, but every finer/coarser said about this grinder was the wrong way round.

Input Schema

Name	Required	Description
`fields`	No
`reason`	No	Optional note, appended to this record's own notes as an ordinary line. Omit it and nothing is written.
`dry_run`	No	true: write nothing, and answer with what the edit would do to the settings already recorded (moved[], checked, epoch, position_moved, position_cleared, rescaled_offsets, resigned_offsets, step_ignored, direction_flipped, recipe_count)
`grinder_id`	Yes	This account's own grinder number, from list_grinders. Never guess one.

Output Schema

Name	Required	Description	Default
`epoch`	Yes
`moved`	Yes
`status`	Yes
`checked`	Yes
`dry_run`	Yes
`message`	Yes
`entry_id`	Yes
`grinder_id`	Yes
`unreadable`	Yes
`moved_count`	Yes
`changed_keys`	Yes
`recipe_count`	Yes
`step_ignored`	Yes
`reads_changed`	Yes
`position_moved`	Yes
`untranslatable`	Yes
`position_cleared`	Yes
`rescaled_offsets`	Yes
`resigned_offsets`	Yes
`direction_flipped`	Yes
`untranslatable_recipes`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / fields / properties / components_spec / description

Previous value: -"JSON array of {name, per_step}, coarsest first — the ring arithmetic of a compound collar, or the ordered settings of a named one"New value: +"JSON array of {name, per_step}, coarsest first: the ring arithmetic of a compound collar, or the ordered settings of a named one"

changedInput schema / properties / fields / properties / nominal_step / description

Previous value: -"Smallest adjustment increment. On a numeric_stepless collar it is the precision labels are recorded in (0.1 records tenths) and the size of one click. numeric_stepped and clicks_single collars record whole steps whatever it says — to record tenths, set setting_scheme numeric_stepless as well"New value: +"Smallest adjustment increment. On a numeric_stepless collar it is the precision labels are recorded in (0.1 records tenths) and the size of one click. numeric_stepped and clicks_single collars record whole steps whatever it says. To record tenths, set setting_scheme numeric_stepless as well"

Changed1 schema field changedSep 27, 2026

addedInput schema / properties / fields / properties / catalog_id

Added value: +{
+  "description": "The maintenance catalog model this grinder is; \"none\" if it is not listed; null to unbind. list_grinders proposes one from the name under maintenance.catalog.match",
+  "type": [
+    "string",
+    "null"
+  ]
+}

AddedSep 16, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Far exceeds the annotations: it explains that only sent keys change, that null (or empty string for text) clears, that required fields can be changed but not cleared, that saving writes maintenance history, opens an unmeasured calibration epoch for locked recipes, marks or clears the collar's current setting, converts measured offsets when a click changes worth, and that direction_convention flips all prior finer/coarser statements without moving a number. This is exactly the destructive/consequential context the destructiveHint flag 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?

Front-loads purpose and the clearing rule, then layers consequences. Dense and mostly earning its length, though the final sentence about direction_convention is long and the middle section packs several distinct behaviors into one sentence, which slightly hurts scannability.

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 destructive, non-idempotent nested-object mutation, it covers write semantics, clearing rules, side effects, dry-run behavior, and escalation to a sibling. An output schema exists and the dry_run parameter already enumerates returned fields, so return values need no further explanation.

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 75%, and the description adds genuine semantics the schema does not: partial-update/patch behavior, null-vs-empty-string clearing rules per type, the ability to omit fields when only reason is sent, and the shared meaning of setting_scheme/nominal_step/components_spec as the lens through which recorded grind labels are read. It does not individually explain every field, but the highest-risk ones are covered.

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?

Opens with a specific verb and resource ("Correct a registered grinder") and enumerates the mutable aspects (name, burrs, collar scheme, nominal step, layout, range, notes). It is clearly a mutation of an existing record, implicitly distinguished from register_grinder, but it never names a sibling explicitly.

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 concrete operational guidance: call with dry_run first when changing setting_scheme/nominal_step/components_spec, and tell the user before saving. It also routes to set_maintenance_offset for resolving an opened calibration epoch. What's missing is an explicit boundary against register_grinder or update_machine for adjacent cases.

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

All ShotPulled tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?