get_build

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

Annotations already cover read-only, idempotent, and non-destructive semantics, so repeating 'Touches: reads only' adds little. The description does add real behavioral context beyond annotations: the three-request cost and the important limitation that older builds may not be found.

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 front-loaded and clearly structured with Returns, Touches, and Bounds sections. It is efficient, though the 'Touches: reads only' line slightly repeats the readOnlyHint annotation and does not earn much space.

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 read-only tool with an output schema and full annotations, the description covers the important gaps: default behavior, request cost, and the not-found boundary. It is complete enough to call correctly, with only minor room for richer guidance on discovering build numbers.

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 0%, so the description must compensate. It explains the key optional parameter well ('the build of that number, or the latest one when none is given'), but project and branch are left without any added semantics.

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 specific verb and resource: 'Read one build of a branch of a project', and explains the default-to-latest behavior. It distinguishes itself from get_branch_settings, but does not explicitly differentiate from close siblings like list_builds or get_build_revision.

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 clear: call with a build number or omit it for the latest, and use get_branch_settings if settings are needed. However, it does not mention list_builds as the way to discover build numbers, so the alternative path for finding a specific build is left implicit.

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