Update Monitor

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

With no annotations provided, the description carries the burden of transparency. It discloses the critical partial-update behavior ('only the fields you provide will be changed') and the need for monitorID. However, it doesn't mention side effects like pushToken invalidation or permission requirements, though these are partly covered in the schema descriptions. A 4 is appropriate as it conveys the core mutation semantics clearly without overstating.

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 three short sentences, front-loaded with the main purpose. Every sentence adds value: purpose, requirement, merge behavior, and a practical tip. Zero filler, perfectly concise.

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 high complexity (38 parameters, nested objects) and the presence of an output schema, the description is sufficient but not exhaustive. It covers the essential usage prerequisites and behavior. It could benefit from a brief example or a pointer to createMonitor for field details, but the combination with the schema makes it complete enough. A 4 balances the need for more context against the schema's richness.

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 has 100% parameter coverage, so the description doesn't need to explain individual fields. However, it adds the overarching rule that only provided fields are updated (server merge), which is a global semantic not visible in any single parameter description. This goes beyond the schema and clarifies how all parameters interact, earning a 4.

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 'Updates an existing monitor configuration' with a specific verb and resource, distinguishing it from createMonitor and deleteMonitor siblings. It also explicitly requires the monitorID, making the purpose unambiguous.

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?

It provides explicit guidance: you must include monitorID, and it recommends using getMonitor first to fetch the current config. It implicitly tells when not to use it (when creating a new monitor) by phrasing as 'existing monitor', and the merge behavior clarifies how partial updates work.

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