blacksmith_sticky_disk_daily

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

No annotations are provided, so the description bears full responsibility for behavioral context. It goes beyond a simple read operation by explaining what the data means (growth curve) and what conclusions to draw. However, it does not disclose details like response format, pagination, or whether data is cumulative, leaving some minor gaps.

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 two sentences, front-loaded with the core purpose in the first sentence, and the second sentence adds valuable interpretation without verbosity. Every phrase earns its place, and it is appropriately sized for the tool's complexity.

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 moderate complexity and absence of an output schema, the description explains what is returned (daily GB held) and how to interpret the data, including actionable insights. It does not specify the exact return shape (e.g., array of date-GB pairs), but for a simple metrics tool, this is sufficiently complete for an agent to understand and invoke the tool.

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 100%, with both org and month parameters well documented in the schema (org defaults to $BLACKSMITH_ORG, month defaults to current and format YYYY-MM). The description adds interpretive context around 'month' (for a month) but does not provide additional parameter-level detail beyond the schema, scoring at baseline.

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 purpose: it provides the daily sticky-disk / Docker-layer-cache footprint in GB held each day for a month, representing the cache growth curve. It distinguishes itself from siblings like sticky_disk_cost by focusing on daily footprint and growth trends, not on cost.

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 implies when to use it: to assess whether the Docker cache is bounded or growing unboundedly. It provides explicit interpretive guidance (steadily-climbing totals signal unbounded cache, flat line signals stable working set) and a remediation action (set max-cache-size-mb). It does not explicitly mention alternatives or when not to use, but the context is clear.

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