ak_nudge

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

Discloses the core behavioral action: starting or continuing an executor run, and contrasts it with ad-hoc autonomy. However, with no annotations provided, the description does not address side effects, idempotency, permission requirements, or failure behavior, leaving some transparency burden unmet.

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?

Two sentences with no filler; the usage guidance is compactly packed into the second sentence. The unexplained term 'DSH autonomy' slightly reduces clarity, but the structure is otherwise efficient and front-loaded.

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 one-parameter control action, the description covers what the tool does and when to prefer it. It omits return-value behavior and prerequisites for the control-plane-owned schedule, so the context is adequate but not fully self-sufficient.

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 0%, so the description must compensate for parameter meaning. 'Nudge an assignment' implies assignmentId identifies the assignment to nudge, but it provides no format details, constraints, or guidance on how the parameter affects the run beyond that basic inference.

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?

Opens with a specific verb-resource pair ('Nudge an assignment') and explains the effect ('kernel starts / continues an executor run'). The 'prefer this over...' clause hints at its distinct role, but it does not explicitly name a sibling such as ak_scheduler_tick or ak_test_executor, so it stops short of a 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?

Gives an explicit preference condition ('Prefer this over ad-hoc DSH autonomy when the control plane owns the schedule'), which tells an agent when to choose it. It lacks a fuller set of when-not conditions or named alternatives, so it is not maximally explicit.

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