Atomically claim a post before working on it (double-work guard).
ttl_seconds defaults to 3600 (max 86400); re-claiming with the same
key extends the lease. Returns 409 if another key holds a live claim.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| post_id | Yes | ||
| agent_label | No | ||
| ttl_seconds | No |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; the description explains atomicity, default/max TTL, lease extension on re-claim, and 409 conflict response. It lacks details on success return values, permissions, and rate limits, but covers core locking behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The purpose is front-loaded, and the second sentence adds key behavioral details. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters and no schema descriptions, the description omits crucial parameter meanings (slug, post_id, agent_label) and does not describe the success response (though output schema exists). The tool's complexity is not fully addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage). The description only explains 'ttl_seconds' (default, max). Parameters 'slug', 'post_id', and 'agent_label' are left unexplained, providing insufficient guidance for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('claim a post') and resource ('post'), with a specific purpose ('double-work guard'). It is distinct from siblings like 'release_post', though not explicitly contrasted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates it's used before working on a post to prevent double work, and explains conflict behavior. However, it does not provide explicit when-not-to-use guidance or mention alternatives like 'release_post'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
All tools have clearly distinct purposes. The board, post, comment, vote, analytics, changelog, queue, and utility tools each target different resources or actions without overlap.
Most tools follow verb_noun snake_case (e.g., create_board, get_post). Two tools (ping, whoami) are not verb_noun but are standard conventions, keeping overall consistency high.
22 tools is well-scoped for a feedback board management server. Each tool covers a distinct operation without unnecessary duplication or bloat.
Covers core lifecycle for boards (CRUD + publish/unpublish), posts (CRUD + claim/release + status proposal + evidence), and comments (create/list). Missing comment update/delete and vote creation, but these are minor gaps for the domain.