Create monitor

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals key traits: evaluation happens inside the plugin, it returns a monitor id, and it is a background operation. It warns against manual polling and points to a companion tool. However, it does not describe lifecycle aspects like timeout behavior, failure states, or how to cancel, which would add further transparency.

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 four sentences, front-loaded with the core purpose, and every sentence earns its place. It avoids fluff and clearly communicates the primary behavior, the return value, the companion tool, and the intended use cases.

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 create tool with nested condition objects and no output schema, the description adequately covers the return value (monitor id) and links to the next step (monitor_wait). It mentions the supported condition types and long-running scenarios. It could mention status/cancel tools or lifecycle states, but the core usage is well covered.

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 75%, and the schema already provides detailed descriptions for condition variants and timeout_seconds. The description only adds 'Installed condition types: command, file, log,' which is already present in the schema. Thus the description adds minimal value beyond the structured schema, so a baseline 3 is appropriate.

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 the tool's function: 'Create a background monitor that watches for a condition and settles when it becomes true.' It specifies the resource (monitor), the action (create), and scopes it to long-running tasks. It also distinguishes from siblings by explicitly mentioning monitor_wait and listing supported condition types (command, file, log).

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 concrete usage context: 'Use this for anything long-running: cluster jobs, builds, deploys, downloads, servers coming up.' It also provides an explicit workflow ('pass it to monitor_wait') and a strong directive ('never write your own sleep/poll loop'). It doesn't explicitly name alternatives like monitor_run or exclude cases, but the guidance is clear and actionable.

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