gc_skill

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

No annotations are provided, so the description carries the burden. It discloses matching behavior (scored against aliases, name, slug, intent tags; project-scoped preferred; mode biases baseline/deep) and lifecycle actions (create/update/deprecate implying mutation). However, it doesn't mention side effects, required auth, or whether mutations are reversible—moderate disclosure for a multi-action registry 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 well-organized with clear sections ('Key actions', 'Matching behavior') and front-loaded purpose. It's efficient but slightly long given the schema already documents parameters well. The action breakdown and matching rules earn their place, though some duplication with schema exists.

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 18 parameters and 7 possible actions, the description covers the action taxonomy and matching behavior well. However, it lacks guidance on what each action returns (no output schema exists to compensate), prerequisites for create/update/deprecate, and cross-action parameter requirements. It's complete for discovery but incomplete for safe invocation of mutation actions. Moderate gap.

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 description coverage is 100%, and the individual parameter descriptions in the schema are already detailed (mode, scope, status, defaults like 'suggest defaults to 5, list defaults to 20'). The description adds cross-parameter context by explaining how action orchestrates the others (e.g., task required for suggest/resolve, name for create, slug for show/update/deprecate). This goes somewhat beyond the bare schema.

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 clearly states this is a 'GC-native procedural skill registry' with a specific 'Key actions' list distinguishing suggest, resolve, list/show, and create/update/deprecate. It distinguishes from siblings like gc_recall (recall memory) and gc_project_registry (project data) by focusing on reusable procedures. However, it doesn't name alternative tools explicitly, so it gets a 4 rather than 5.

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 contextual guidance: 'Use this when you want to know whether GC already has a reusable procedure for a task before inventing a new workflow.' It differentiates suggest from resolve ('safe yes/no pick') and explains list/show vs create/update/deprecate. It lacks explicit 'when not to use' exclusions or named alternatives, so it misses 5.

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