gk_mode

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: debug_engine uses static scan and token heuristics (not a live debugger), tool_propose searches but does not install, and unknown actions return an allowed list. These add meaningful context beyond the schema, though it does not cover all side effects or action-specific outcomes.

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 single dense sentence that packs many details: feature list, action pattern, debugger clarification, tool_propose distinction, and unknown-action behavior. It is concise and information-dense, though the heavy use of abbreviations and packed lists might reduce readability slightly.

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 (29 actions, multiple sub-modules) and the presence of an output schema, the description is far from complete. It does not list available actions, explain how each action works, or describe return structures. The unknown-action fallback is helpful, but overall the description leaves major gaps for an agent to operate correctly.

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 0%, so the description must compensate. It mentions 'Pass action= and optional args={}' and explains that unknown action returns the allowed list, but does not enumerate the 29 actions nor describe valid args values. The description adds minimal semantic detail beyond what the schema already shows (action required, args optional with default null).

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 lists several features (modes/protocols/skills, ultradeep/view, debug_engine, tool_propose, plan_refute) and indicates an action-based interface ('Pass action=...'), but lacks a clear verb like 'execute' or 'manage'. It does mention unique capabilities distinguishing it from siblings, but the primary purpose is not immediately obvious to an agent.

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 provides implicit guidance through caveats: debug_engine is 'not a live debugger' (suggesting another tool for that), and tool_propose is 'search≠install' (clarifying it's not for installation). However, there is no explicit statement of when to use this tool versus alternatives, nor any mention of sibling tools.

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