mangome_work

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

With no annotations, the description carries the full load, and it does disclose one genuinely non-obvious trait: RECONCILE_ASSIGNMENT is read-only underneath but the facade may auto-fire ENTER_WORK, so a nominally read operation can cause a write. That is real value. It stops there, though — nothing about side effects of the other 26 operations, permission/auth requirements, idempotency, or failure behavior.

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?

The purpose is front-loaded in the first sentence and the text is short with no padding. However, the middle sentence ("intentionally more automatic than the precise advanced capability surface") is jargon that never names the surface it contrasts against, so it does not earn its place.

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?

An output schema exists, so return values need not be explained. But for a single dispatcher exposing 27 operations with 0% parameter coverage and no annotations, the description leaves the agent unable to know what most operation values do or what payload each expects — a substantial gap relative to the tool's complexity.

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 description coverage is 0% on two parameters. The description names only 2 of the 27 enum values (RECONCILE_ASSIGNMENT, ENTER_WORK) and says nothing about `payload`, which is presumably where per-operation inputs live. With 0% schema coverage the description must compensate, and it does not.

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 first sentence gives a verb+resource ("Enter/progress governed work"), but "governed work" and "allow-listed transitions" are abstract and never grounded in the mechanics an agent actually needs — that a call dispatches one of 27 enumerated operations, each with different semantics. The mention of RECONCILE_ASSIGNMENT and ENTER_WORK partially illustrates the model, but the sibling tools (mangome_observe, mangome_effect, mangome_control, etc.) are never referenced, so routing is left to inference.

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?

There is one operational instruction — "Ordinary agents must not stop to ask the user for internal WorkIdentity vocabulary" — and an implicit claim that this facade is "more automatic" than an unnamed "precise advanced capability surface." That alternative surface is never named or mapped to a sibling tool, so the agent gets no explicit when-to-use-this-vs-that guidance.

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