push_artifact

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

ANNOTATION CONTRADICTION: readOnlyHint=true while the description says 'write edited fields back' and 'Overwrites the listed fields with NO merge' — a clear write operation contradicts a read-only annotation. openWorldHint=true also conflicts with the explicit requirement of WRITE_ENABLED=true. The description does add good behavioral context (NO merge, abort on conflict) but the contradiction is serious and disqualifies it.

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 description is a compact three-sentence block that front-loads the core action and key prerequisite (WRITE_ENABLED=true). It includes the critical NO-merge and expected_updated_on conflict behavior in the same sentence, which is dense but efficient. No wasted words, though it could be slightly better structured with the merge behavior separated.

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?

This is a complex mutation tool with no output schema and a serious annotation contradiction, but the description does cover prerequisites, merge behavior, conflict detection, and both field input modes. It lacks explicit return-value or success/failure contract information, and the openWorldHint with WRITE_ENABLED requirement leaves some ambiguity about environment constraints. Reasonably complete for the complexity but not outstanding given the contradictory annotations.

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 100%, so the schema documents all four parameters. The description adds meaningful semantics beyond the schema: it explains the dual meaning of 'fields' (inline vs. on-disk from NOWAIKIT_SYNC_DIR), and gives context on expected_updated_on (aborts with CONFLICT if changed). This exceeds the baseline-3 judgment.

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 uses a specific verb+resource ('Local sync: write edited fields back to an artifact') which distinguishes it from siblings like pull_artifact, sync_status, and find_artifact. It clearly names what the tool does. However, it relies on the tool name to convey much of the purpose, though the mention of 'write edited fields back' and 'Overwrites the listed fields with NO merge' adds useful scoping.

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 gives clear context: this is for the push side of a local sync workflow ('Local sync'), and it correctly references running sync_status first and passing expected_updated_on. It implies usage within a pull-push sync cycle. It doesn't explicitly name alternative tools or when-not-to-use, but the workflow context (requires pull/sync_status first) is actionable guidance.

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