get_build_revision

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description goes further with a concrete cost bound (six requests to Odoo.sh) and a failure mode (a build older than the branch's latest ones is not found). It also warns that the branch's Odoo revision may not be the build's, a meaningful semantic caveat. The submodule sentence is hard to parse, which keeps it from 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?

Purpose is front-loaded, but the Returns block largely restates the opening paragraph, repeating the Odoo-revision caveat and the submodule limitation nearly verbatim. Given an output schema already exists, that repetition is waste.

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 lookup with an output schema and full annotation coverage, the description supplies the important operational facts: cost, failure bound, and the branch-vs-build revision ambiguity. Only the identification scheme for project and branch is missing.

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 coverage is 0%, so the description must compensate. It explains build_id well (a build number, defaulting to the latest), but says nothing about the format or identity of 'project' and 'branch' — e.g. slug vs. display name — leaving two required parameters undocumented in both places.

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?

States a specific verb and resource set: it reads what a build runs — head commit, Odoo version, and the branch's selected Odoo revision with each repository commit. An agent can tell it is a revision-inspection read, distinct from status/log tools. It does not explicitly contrast itself with get_build, leaving the boundary to inference.

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 build of that number, or the latest one" implies when build_id is omitted, and the Bounds line flags that older builds are not found. But there is no explicit when-to-use-this-vs-get_build/get_branch_settings guidance and no stated prerequisites.

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