hub_sync

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

With no annotations, the description must fully disclose behavior. It reveals that git facts are automatically collected and that the card is rewritten (destructive write), but lacks details on idempotency, error handling, permissions, or side effects on existing hub data. The mention of rewriting implies mutation, but transparency is incomplete.

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 two sentences long, no wasted words. The first sentence states the primary function, and the second adds critical detail about git facts and the digest parameter. It is front-loaded and efficient.

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?

Given the tool's complexity (4 parameters, no output schema, no annotations), the description lacks details on return values, error conditions, and prerequisites (e.g., hub setup). It explains the core mechanism but leaves gaps about what the agent can expect after calling 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%, so baseline is 3. The description adds context by linking 'digest' to the agent's summary and explaining that it causes the card to be rewritten. However, the schema descriptions already clearly define each parameter; the description does not clarify types, defaults, or ranges beyond what the schema provides.

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 'Sync a project folder into the hub' with a specific verb and resource, and adds details about auto-collecting git facts and rewriting the card via digest. It distinguishes from siblings like hub_get (read-only) and hub_card_set (card updates without syncing), but doesn't explicitly contrast or mention alternatives.

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?

No guidance is provided on when to use this tool versus siblings like hub_card_set or hub_brief. There is no mention of prerequisites, use cases, or conditions that make hub_sync preferable. The description simply states the action without contextual usage advice.

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