gc_work

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

No annotations are provided, so the description carries the behavioral disclosure burden. It reveals search bypasses project_id tagging, punctuation-only queries return annotated empty results, list returns `total` pre-limit count, and ready has no default. This adds meaningful behavioral context beyond names, but doesn't discuss mutation effects, permission requirements, or what dependencies/DAG state changes look like.

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 reasonably compact for a 20-parameter, 19-action tool, but front-loads a dense action list that is somewhat redundant with the enum in the schema. The essential guidance about search, ready, and plan is packed at the end, and some param context (search punctuation behavior, limit semantics) could be trimmed since these are also documented in the input schema.

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 19-action, 20-parameter tool with 100% schema coverage and no output schema, the description covers the critical usage patterns (search for dedup, ready for unblocked, plan for critical path) reasonably well. However, it doesn't explain return-value structure or describe what most of the 19 actions produce, and with no output schema the agent must guess the shape of results for many actions.

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 value by grouping actions with their relevant params (q for search, days for stale/focus, dry_run for backfill_projects, limit defaults per action, include for show comments). It also explains action-specific defaults like list default 50/cap 500 and search default 10/cap 50, and clarifies punctuation-only search behavior, going beyond a bare parameter list.

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?

Description states 'Work coordination with dependency DAG' and enumerates 19 action verbs, making the purpose clear. It distinguishes from siblings like gc_plan (issue planning) and gc_workflow (workflow orchestration) by focusing on task issues with dependencies, but doesn't explicitly name sibling 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?

Description gives concrete usage guidance: 'Use action=search to check if an issue about a topic already exists (FTS, ranked, matches title+description regardless of project_id tagging) instead of listing the whole DAG.' Also recommends 'ready' to see what's unblocked and 'plan' for critical path. However, it doesn't explicitly say when NOT to use this tool vs. gc_plan or gh_issues.

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