get_build

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is established. The description adds the useful scoping detail that this applies to publish or download build jobs, but it does not disclose additional behaviors such as return shape, not-found handling, or project designation mechanics. With annotations covering the read-only nature, a middle score is appropriate.

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 with no filler. Every phrase contributes meaning: the operation, the resource subtype, the lookup key, and the project scope. It is appropriately sized for a simple single-parameter getter.

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 one-parameter read-only getter, the description is mostly complete: it names what is returned and how it is identified. The main gap is that it does not describe what the returned build job object will contain, and 'designated project' is not explained since the schema only accepts buildId. Still, the tool is simple enough that this is a minor omission.

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 carries the burden for parameter semantics. It only repeats the idea of 'by id' without adding anything beyond the schema property name 'buildId'. The schema itself already provides type and exclusiveMinimum, but the description does not clarify the meaning or origin of the buildId beyond what the property name already implies.

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 operation ('Get'), the resource ('a publish or download build job'), the selector ('by id'), and the scope ('from the designated project'). This differentiates it from siblings like list_builds (listing), create_build (creating), and delete_build (deleting), so an agent can identify the intended tool without inspecting the schema.

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 phrase 'by id' implies this tool should be used when a specific buildId is already known, and the mention of 'from the designated project' gives some context. However, there is no explicit guidance about when not to use it or which sibling alternative to choose when the buildId is unknown, such as list_builds.

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