invariance_monitor_create

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

Annotations provide only readOnlyHint=false and destructiveHint=false; the description adds that the monitor can optionally emit signals, findings, or reviews on match, which is useful side-effect context. However, it does not clarify whether creation alone triggers evaluation, how scheduled or manual evaluation relates to the created monitor, or whether authorization or validation steps are involved. The description neither contradicts annotations nor fully discloses behavioral traits like immediate activation or persistence semantics.

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, front-loaded sentence that clearly states the action and the key behavior. Every clause contributes meaning, and there is no filler or repetition of schema details. It is appropriately concise for a tool with a comprehensive input schema.

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?

With no output schema, the description does not mention what the create call returns (e.g., monitor ID or object), nor does it explain that the monitor may run on a schedule or must be manually evaluated. The schema thoroughly documents the request body, but the overall tool context is incomplete for an agent that needs to understand the full lifecycle after creation. Given the moderate complexity, this is a notable but not critical 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?

The schema covers the single body parameter with a very detailed description, including required fields, valid evaluator shapes, optional settings, and an example. The tool description itself adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate given 100% schema coverage.

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 uses a specific verb ('Create') and resource ('monitor'), and clearly explains what the monitor does: evaluates an event-shaped predicate against nodes/runs and optionally emits signals, findings, or reviews. This distinguishes it from other monitor-related siblings like monitor_list, monitor_get, or monitor_evaluate, which involve different lifecycle stages.

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 does not state when to use this tool versus alternatives. While the verb 'Create' implies a new-monitor workflow, there is no explicit guidance around prerequisites, when to choose create over monitor_update or monitor_evaluate, or any exclusionary conditions. An agent must infer usage entirely from the tool name and context.

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