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

Annotations already declare non-read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond them: null text resets to the workspace's own words, omitting text preserves the current value, and settings are merged and validated. This richer partial-update semantics is exactly the behavioral context annotations can't convey.

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?

Front-loaded with the action, but the rest is a single heavily-nested sentence of semicolons and parentheticals that is dense to parse. No padding exists, yet the cramped structure reduces readability.

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?

For a 5-param mutation tool with 40% schema coverage and no output schema, the description covers the tricky write semantics well enough to call it correctly. The main gap is that the 'act' parameter itself is never defined, and the 'checked' behavior on settings is asserted without detail.

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 coverage is only 40%, so the description must compensate, and it does for the two undocumented params: 'text' null-vs-omitted semantics and 'settings' merge-and-check behavior are both explained. 'act' itself is left undefined and tommo/job rely on their schema notes, so it is not fully complete.

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?

States a specific verb and resource: 'Write an act's page on a job.' This clearly distinguishes it from the read counterpart read_an_act and from other save_* siblings. It stops short of 5 because 'act' is unexplained jargon and the description leans on context the agent may not have.

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?

Provides a precondition — 'Only an act the job takes (see read_a_job)' — which routes the agent to a sibling to validate eligibility. However, it gives no explicit when-not or comparison against read_an_act / other write tools, so the usage guidance is implied rather than spelled out.

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