listener

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

With no annotations provided, the description carries the full burden and does: it discloses idempotency guarantees (exclusive flock, no duplicate sessions), the supervision semantics of disable (finishes the current worker, then exits), and a safety boundary ('No PID is ever killed from here'). It also scopes the returned data ('never task payload'), which preempts a plausible agent assumption.

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?

Front-loaded with identity and scope, then segmented by action, with zero filler sentences. The register is telegraphic ('removes the disabled marker', 'writes the marker'), which compresses well but occasionally forces the reader to reconstruct grammar rather than read meaning directly.

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 single-parameter tool with an output schema and no annotations, this covers the operations, their side effects, idempotency, and the safety boundary. What is left unsaid is failure behavior (e.g., what status reports when no listener is running, or what happens on enable when already enabled) and any auth requirement beyond the AGENT_ID scope.

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% and the single 'action' parameter has no enum, so the description must supply the value domain — and it does, defining status/enable/disable with the exact behavior of each. It falls short of 5 because the values are only implied by colon-prefixed labels rather than stated as a closed set, leaving open whether other actions exist.

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 opening line names a specific resource (this agent's own background listener) and a hard scope limit (AGENT_ID only), and the three sub-operations status/enable/disable define exactly what 'manage' covers. It is clearly distinct from the messaging siblings, though the generic verb 'Manage' does the least work in the sentence and 'listener' is only defined indirectly via the task/worker/flock details.

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?

Each action is given a use condition: status to inspect, enable to clear the disabled marker, disable to stop taking new work gracefully. The closing line 'Dispatch itself stays governed by systemd/config.json auto.<agent>' is an explicit exclusion telling the agent not to reach for this tool to change dispatch, though no sibling or alternative tool is named as the route for that.

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