watch_workload

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

With no annotations provided, the description carries the full disclosure burden and does a solid job: it states the tool is stateless with no server-side storage, that the caller must persist the baseline JSON in a git repo or other durable location, and that the return is a structured drift report with per-cloud delta plus SKU-level attribution. It does not explain failure modes (e.g., mismatched or corrupted baseline, what happens when the alert threshold is crossed versus merely reported), which keeps it short of a 5.

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 substantive content is front-loaded and dense — baseline capture, drift comparison, statelessness, persistence location, and target audience each appear once. The opening clauses ('Cost Drift Sentinel — turns cloudprice from query tool into agent capability') are promotional padding that the agent gains nothing from, keeping it from a 5.

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 an 11-parameter, nested-object tool with no annotations and no output schema, the definition covers the highest-risk gaps: how the baseline lifecycle works, that state lives client-side, what the report contains, and the scheduled-agent usage context. What's missing is enough parameter guidance to compensate for 27% schema coverage and any note on error/threshold behavior, so it is good but not fully complete.

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 only 27% across 11 parameters, so the description needs to compensate and largely doesn't. The only parameter meaning it reinforces is baseline (first call null, later calls pass it back), which the schema already documents; the ten workload-specification parameters (compute, storage, egress, databases, objection_storage, commitment, alert_threshold_pct, etc.) and their nested fields get no clarification of intent or interplay from the description.

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 states a concrete behavior — capturing a baseline of per-cloud monthly cost on first call and computing a drift report against it on later calls — so an agent can tell what the tool does. It never names a sibling (e.g., compare_workload or get_price_history), so differentiation from the many cost-comparison tools is left inferred, and the 'Cost Drift Sentinel — turns cloudprice from query tool into agent capability' framing adds branding rather than additional precision.

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?

Usage is spelled out in two clear modes: call with no baseline first, then call with the saved baseline on subsequent runs, aimed at scheduled agents. There is no statement of when to prefer this over compare_workload, get_price_history, or forecast_spend, and no exclusions, so the agent must infer alternatives on its own.

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