Snapshot portal content to git

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

The description adds material behavioral detail beyond the annotations: the coverage verification ('staged counts are checked against live listings'), the rollback caveat, and the prerequisite 'Requires PORTAL_VC_DIR.' It aligns with readOnlyHint=false and idempotentHint=false, and does not contradict any annotation. It goes beyond the basics expected for a mutation tool.

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 dense but efficient, front-loading the core action ('Export every content resource... AND commit') before adding usage timing and behavioral caveats. Every sentence carries distinct value, though it could be broken into clearer sentences for readability. It is not verbose enough to warrant a 3, but not as crisp as the two-sentence example for a 5.

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 complex export/commit tool with multiple resource kinds and a coverage check, the description covers the essential facts: what is exported, when to use it, the verification mechanism, and the required environment variable. It doesn't describe return values, but there's no output schema. The missing 'message' parameter usage is covered by the schema, so the description is sufficiently complete for an agent to decide when and how to call it.

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% for the single optional 'message' parameter, which the schema already documents ('Commit message (default: 'snapshot')'). The description does not add any new meaning for this parameter, so the baseline of 3 is correct. The mention of PORTAL_VC_DIR is an environment variable, not a parameter, and doesn't enhance parameter understanding.

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 states a specific verb ('Export'), resource scope ('every content resource... AND datasources'), and destination ('version-control repo and commit'). It clearly distinguishes itself from sibling tools like vc_status or vc_diff by describing a distinct snapshotting action, leaving no ambiguity about what this tool does.

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?

It provides explicit timing guidance ('Run once to seed history, or anytime to capture a checkpoint'). While it doesn't name alternatives or state when not to use it, the context is clear enough that an agent can choose this tool for snapshot creation without confusion. A 5 requires explicit when-not/alternatives, which is absent, so 4 is appropriate.

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