Loading ToolBench
Visual feedback as agent work packets. Stakeholders drop pins on your live app; your AI coding agent reads each pin (selector, screenshot, DOM, thread, acceptance criteria) via MCP and ships the fix.
PinCushion MCP exposes 17 tools for managing visual feedback annotations. Strengths: clear verb-noun naming (list_pins, get_pin, claim_pin), all tools have descriptions, and the core workflow is well-defined (discovery → claim → approve → implement). Significant gaps: no input parameter descriptions visible in provided schema samples, no documented output schemas, limited error handling guidance, no tool annotations (readOnlyHint/destructiveHint/idempotentHint), no pagination controls on list operations. The server.js excerpt shows tool registration but parameter descriptions are missing from the input schema objects shown. Risk classification is metadata but not returned to agents. Tools like `list_pins` and `implement_approved_pins` return potentially large result sets with no pagination documented.
Approve a pin for implementation (mark as 'ready' or 'approved').
Mark a pin as being worked on by the agent (transition from 'open' to 'claimed').
Commit a pin implementation with a structured trailer block (Pin-ID, Reviewed-By, etc.).
Register or update a project in .feedback/projects.json, idempotently creating deploy hooks and cloud members.
Generate AI critique feedback on a pin using the project's brand context.
Decline a pin with optional feedback, transitioning its status to 'declined'.
Ensure a pincushion/* branch exists for a given page (creates from default if needed; checks out and rebases if exists).
Missing parameter descriptions in input schemas. The provided schema objects show 'type' and 'description' keys for parameters, but descriptions are minimal or generic (e.g., 'Optional project ID to filter pins'). Rubric requires explicit parameter descriptions clarifying format, constraints, and valid values. Without these, LLMs cannot reliably infer when to pass optional parameters or what format is expected.
No documented output schemas. Tool descriptions state what they return (e.g., 'Fetch a single pin by ID, including its full thread, DOM snippet, screenshot, and acceptance criteria') but no formal schema is provided showing which fields agents should expect. This forces LLMs to infer structure and makes downstream tool chaining fragile.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 50 | 2026-07-28+ | v2 |
Mark a pin as implemented, update its status, and push to cloud if configured.
Fetch a single pin by ID, including its full thread, DOM snippet, screenshot, and acceptance criteria.
Read-only: fetch project context (brandContext, critiqueContext) without mutations or network calls.
Get the status of the last cloud sync, including plan, next sync time, and notification queue.
Get all pins in 'ready' or 'approved' status, ready for the agent to implement.
Infer likely source files that contain a UI component based on DOM hints (component names, classes, data attributes).
List all annotation pins in the .feedback/ directory, optionally filtered by status.
Recompile brand context from signals (used when project evolves or pin count changes significantly).
Gather and compile brand context (readme, tokens, competitors, mission) for the critic subagent.
Manually trigger a sync with Pincushion Cloud (Supabase) to fetch new/updated pins and push local status changes.
List operations lack pagination. Tools like list_pins, implement_approved_pins, and infer_likely_files can return potentially large result sets (all pins in a project, all branches matching a pattern) but have no limit, offset, or cursor parameters documented.
Missing tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools are manually tagged with Risk metadata (READ_ONLY, WRITE) but this is not exposed to the MCP client via tool annotations. The MCP spec supports tool.readOnlyHint (boolean) and tool.description references to mutability, neither is visible in the provided code. This leaves agents unable to auto-classify actions as safe vs. destructive.
Error handling is not documented in tool descriptions. None of the tool descriptions mention what errors can occur, when to retry, or how to recover (e.g., 'Pin not found. Call list_pins to see available pins.' or 'Project not found. Call configure_project first.'). Rubric requires error responses to guide agent recovery; absence from descriptions suggests limited error guidance.
Vague parameter descriptions for enums. Parameters like 'status' in list_pins show example values ('open', 'ready', 'approved', 'implemented') but are not formally constrained as enums. Similarly, 'preset' in commit_pin_fix lists values ('minimal', 'standard', 'full') in the description rather than as a JSON Schema enum. LLMs cannot parse free-text constraints; they need formal enum definitions.
Missing composition guidance. Multi-step workflows (e.g., 'claim a pin, then implement it, then commit the fix') are implied by tool names but not documented. No tool description states 'call claim_pin first before approve_pin' or 'after fix_and_resolve, call sync_annotations to push to cloud'. This forces agents to infer correct sequencing.
Idempotency not declared. Tools like fix_and_resolve, configure_project, and commit_pin_fix perform state mutations, but idempotency is not documented. Agents that retry on transient failures need to know: is it safe to call fix_and_resolve twice with the same pinId? (Likely yes, but not stated.) Explicit idempotency claims enable safe retries.