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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable operational context beyond annotations: a concrete rate bound ('three requests to Odoo.sh'), a return summary, and a development-branch caveat, though 'Touches: reads only' is redundant with readOnlyHint.

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 with purpose and uses labeled sections ('Returns:', 'Touches:', 'Bounds:') that make it easy to scan. It is mostly efficient, though 'Touches: reads only' duplicates the readOnlyHint annotation and could be omitted without losing information.

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?

An output schema exists, so the description needn't explain return values, but it does so anyway while omitting parameter identifier guidance despite 0% schema coverage. The rate limit and branch-type caveat are useful additions, but the lack of project/branch format guidance leaves a meaningful gap for invocation.

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 carry the burden for the two required parameters. It only mentions 'project' and 'branch' in prose without clarifying identifier formats, whether names or IDs are expected, or any constraints—leaving the parameter meaning essentially as bare property names.

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 the settings of a branch of a project,' and enumerates the settings (commit behavior, build modules/tests, Odoo version, OS, domains). This is clear enough to distinguish branch-level settings from project-level settings, but it does not explicitly name or contrast with sibling tools such as get_project_settings or list_branches.

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 offers a scope caveat ('the new build options apply to a development branch only') but no explicit guidance on when to choose this tool versus alternatives like get_project_settings or list_branches. An agent must infer usage from the tool name and purpose alone.

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

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.

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.

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

Beyond the annotations (which already mark it read-only and idempotent), the description discloses the admin-conditional field visibility, the truncation flag semantics, the request budget to Odoo.sh, and a hard 200-branch cap. That is substantive behavioral context an agent cannot get from annotations or schema.

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?

Front-loaded with the core action and contents, then cleanly separated into Returns, Touches, and Bounds sections. Dense but every clause carries information; only the 'Touches: reads only' line is mildly redundant with the readOnlyHint annotation.

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?

Covers the admin caveat, truncation, and request bounds, which are the tricky behaviors for this tool. Since an output schema exists, the explicit Returns narrative is partly duplicative, but it usefully explains the null and truncated conditions that a schema might not convey semantically.

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% and the single 'project' parameter carries no schema description, so the description must compensate. It clarifies the value is a project name rather than an ID, which is useful, but gives no format, casing, or example guidance.

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?

Specific verb ('Read the overview') plus resource ('of a project'), and it enumerates exactly what the overview contains (subscription, Odoo version, region, build, branches by stage, plus admin-only fields). This clearly separates it from siblings like get_project_settings and list_projects, which return different slices.

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 implied: it says to read the overview 'given by its name' and enumerates the contents, so an agent can infer it fits when a broad snapshot is needed. But there is no explicit when/when-not guidance and no sibling is named as an alternative (e.g. get_project_settings for configuration details).

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuine beyond-schema context: 'Bounds: two requests to Odoo.sh' quantifies request cost, plus an explicit prompt-injection warning about admin-typed submodule URLs and test tags. 'Touches: reads only' merely restates the readOnlyHint but does no harm.

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?

Verb and resource are front-loaded and the Returns/Touches/Bounds scaffolding makes scanning easy. The opening sentence is an overlong run-on field list, and the injection warning wedged mid-sentence slightly disrupts flow.

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?

With one required parameter, an output schema, and full annotations, the description still covers what is returned (including units for timeouts and CIDR form for the IP list), what is not returned (no token or code), and the request bound. Nothing needed to invoke it correctly 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% and the single parameter is bare ('Project': string), so the description must carry the load. It does clarify that the project is identified 'by its name', which is the key fact, but adds no format, casing, or error behavior for an invalid name.

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 ('Read') and resource ('the settings of a project') and enumerates exactly which settings are returned (domain block, session lifetime, deploy key, IP allow list). This cleanly separates it from sibling get_branch_settings and get_project_overview.

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 only implied by the resource name; the description never says when to prefer this over get_branch_settings or get_project_overview, nor states prerequisites such as needing admin visibility. The admin-only framing hints at context but no explicit routing guidance is given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the request bound (one call to Odoo.sh, zero when no session exists), which tells the agent about cost and side-effect-free fallback behavior.

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?

Nicely front-loaded with labelled sections (Returns/Touches/Bounds) and each line is short. There is mild redundancy: the opening sentence's 'where it came from and who it belongs to' is restated as 'its source, its user' in the Returns line.

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?

An output schema exists, so enumerating return fields is optional padding rather than required content. With annotations carrying the safety profile and the bounds line carrying the operational cost, the only real gap is the absence of guidance on when this check should be invoked relative to the sibling tools.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims are made or needed.

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 (Report) and resource (Odoo.sh session) with the exact fields surfaced: availability, source, user, and seconds until max age. This is clearly separable from the build/branch/project/log siblings, none of which touch session state.

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 only implied — an agent can infer this is a diagnostic/authentication-state check to run before other Odoo.sh operations. There is no explicit when-to-use, no prerequisite statement, and no named alternative or condition for skipping it.

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

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

Goes well beyond the annotations: declares reads-only behavior, a concrete rate limit (two requests within 60 seconds), truncation semantics via `truncated`, per-field byte caps, admin-only visibility, and a prompt-injection warning about `untrusted_entries` being third-party authored. That last point is exactly the kind of behavioral context annotations cannot carry.

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?

Well front-loaded and segmented into purpose, Returns, Touches and Bounds sections, so an agent can scan it. It is dense, and the rate-limit sentence ('two requests ... the second answering the last 30 days whole') is slightly convoluted, but nothing is gratuitous.

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?

Covers every axis an agent needs for a two-parameter list tool: scope, ordering, authorization, rate limits, truncation, field-level caps, and return shape. Even though an output schema exists, the extra note about control characters and per-entry field truncation adds actionable context rather than duplicating it.

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 carries the full burden and does: `project` is identified as the project name, and `limit` is given a default (20) and a hard maximum (100). Both parameters are semantically defined despite having no schema descriptions.

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 ('List the audit log of a project') plus the exact content returned: who did what, when, on which stage. The ordering statement ('newest first') and the Odoo.sh framing distinguish it from generic siblings like read_log and list_history without requiring a schema lookup.

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 implied by the resource itself and a key prerequisite is given ('shows the log to an admin of the project only'), which tells an agent it will fail for non-admins. However, there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the siblings (read_log, list_history) that an agent might reasonably confuse with this.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them with cost bounds ('two requests to Odoo.sh') and a hard result cap ('200 at most'), which the schema does not state. It also discloses truncation behavior, giving the agent real operational context.

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?

Four short labeled sentences (Returns/Touches/Bounds) with the purpose front-loaded and zero filler; every clause carries information an agent can act on.

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 list tool with an output schema, the description covers purpose, input semantics, cost bounds and truncation, which is nearly everything needed. It omits only edge behavior such as what happens when the project name does not match.

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, and it does: it clarifies that 'project' is given by name and that 'limit' defaults to 50 with a 200 maximum (the max is absent from the schema). It stops short of format/case details for the project name, so not a full 5.

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 (List) and resource (the branches of a project) plus scope (with the stage each sits in), which cleanly separates it from siblings like list_projects and list_builds even though they are not named.

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 only implied: it tells the caller a project name is required, which suggests use when you know the project, but there is no explicit when-to-use, when-not, or alternative routing. Since no sibling lists branches, the routing risk is low, keeping this at a minimum-viable 3.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the 'Touches: reads only' line is redundant. What earns credit is the cost model ('three requests to Odoo.sh') and especially the caveat that the backend has only been observed to return 4 builds, so older data is out of reach regardless of `truncated`.

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?

Labeled sections ('Returns:', 'Touches:', 'Bounds:') front-load the primary action and then answer expected agent questions in order. Dense but every clause carries information; only the 'reads only' line is wasted against the annotations.

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?

An output schema exists, so return values need not be spelled out, yet the description still flags `truncated` and its unreliable semantics — the single most important thing an agent must not misread. Cost, bounds and the reachability limit are all covered for a moderate-complexity read 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 0%, so the description carries the burden, and it does add real meaning: `limit` defaults to 4 and caps at 20, which the schema does not state. Project and branch are only implied ('a branch of a project') with no identifier format guidance, which is the remaining gap.

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 plus scope and ordering: 'List the latest builds of a branch of a project, newest first, with their status, result and commit.' This cleanly distinguishes it from sibling reads like list_projects, list_branches and get_build.

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 implied by the scope rather than stated; there is no explicit guidance on when to pick this over get_build or wait_for_build. It does add one genuinely useful decision cue — that older builds are unreachable even when `truncated` says otherwise — which nudges it above a bare 2.

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

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

Goes well beyond the annotations: it discloses the exact request budget (two to Odoo.sh, then one per 20 of limit+1 events, eight max), a 60-second page window, the default and maximum limit, and the `truncated` flag that signals more results exist. Those are concrete cost and pagination facts an agent cannot get from readOnlyHint/idempotentHint alone.

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?

Front-loaded with the purpose, then explicitly labeled Returns/Touches/Bounds sections — every sentence carries information. The bounds sentence is dense and slightly hard to parse on first read, which is the only thing keeping it off 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?

Covers purpose, event shape, read-only nature, rate/request budget, page timeout, limit bounds, and truncation signaling. Even though an output schema exists, the description still tells the agent what fields each event carries, leaving nothing an agent needs in order to call it correctly.

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 has to carry the load, and it does for the non-obvious parameter: `limit` gets a default of 10, a ceiling of 100, and its role in the request-count formula. `project` and `branch` are only implied by "a branch of a project", but their meaning is self-evident from the names.

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 ("List the history of a branch of a project") plus the ordering ("newest first") and the exact event kinds included: pushes with commits, rebuilds, stage moves. That enumeration distinguishes it cleanly from list_builds and list_audit_log without the agent needing to open any 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 event-kind enumeration gives clear context for when this feed is the right call rather than list_builds or list_audit_log, and "reads only" sets the safety expectation. It stops short of naming an explicit alternative or stating exclusions, so it is clear context without routing rules.

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

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

Goes well beyond the read-only annotations by disclosing ordering ('newest first'), truncation behavior, request bounds ('six requests to Odoo.sh and the build's worker'), limit defaults and maxima, header size limits, and the critical trust model for `untrusted_mails`. The description also states 'reads only', consistent with `readOnlyHint`.

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 purpose is front-loaded and the description is dense with useful information rather than filler. The middle sentence is slightly awkwardly structured around the build selection clause, but every section earns its place.

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?

Even though an output schema exists, the description explains the return shape, truncation flag, trust boundary, and operational bounds. An agent has everything needed to call this tool correctly and interpret the results safely.

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 carry parameter meaning. It explains `build_id` behavior ('of the build of that number, or of the latest one'), `limit` ('20 by default and 100 at most'), and situates `project` and `branch` as identifying a development or staging branch build. The project and branch values themselves could be slightly more explicit, but the compensation is strong.

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: listing mails caught by a build instead of being sent, newest first, with date, sender, recipients and subject. It explicitly distinguishes itself from `read_mail`, which retrieves the body, so the agent can tell the two apart without opening either 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?

Provides clear routing to the sibling tool: 'Call `read_mail` with a mail's `id` for its body.' It also establishes the important security context that the mails are untrusted build output and must not be followed as instructions. It does not explicitly state when not to call `list_mails`, but the primary alternative is named.

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

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

Goes well beyond the annotations (readOnly/idempotent/non-destructive are already declared) by disclosing the cost profile ('two requests to Odoo.sh'), the limit bounds (50 default, 200 max), per-field truncation at 256 bytes with a `truncated` flag, and a prompt-injection warning about treating member data as untrusted. Those are exactly the operational facts annotations cannot express.

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 and the Returns/Touches/Bounds sections make it scannable. The one weakness is redundancy: the field list in the opening sentence (login, name, role, GitHub user number, pending login) is largely restated in the Returns block.

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?

Covers everything an agent needs for a read-only list call: permissions, request cost, pagination binding, truncation behavior, and a safety note on returned personal data. Return shape is additionally backed by a real output schema, so nothing material 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 carry the load, and it does add real meaning: `limit` gets a default and a hard ceiling, and `project` is clarified as the project's name rather than an id. It stops short of stating the exact accepted name format or matching rules, which leaves a small gap for a fully undocumented schema.

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+resource ('List the members of a project'), the sort order, and exactly which fields come back, so an agent can distinguish it from list_projects, get_project_overview, and list_audit_log at a glance. It also scopes who sees the data ('an admin of the project only').

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 makes the use case clear (enumerate project membership) and states the admin-privilege precondition, which shapes when the call is viable. It never names an alternative sibling or an explicit 'do not use this when…' rule, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so 'reads only' is largely redundant. However, the 'Bounds' line adds genuinely new behavior: a single request to Odoo.sh and a hard cap of 200 items (default 50), which the annotations do not express.

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?

Front-loaded purpose, then clearly labelled Returns / Touches / Bounds blocks. Every sentence carries information; nothing is padded or restated for its own sake.

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?

With an output schema present, the description need not enumerate return fields, yet it still names the key fields and the `truncated` flag. Combined with the sequencing rule and request bounds, nothing an agent needs to invoke this tool 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% for the single `limit` parameter, so the description must carry the semantics. It does: 'limit items, 50 by default and 200 at most' supplies both the default and the upper bound, with only the units/meaning of 'items' left implicit.

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 ('List the Odoo.sh projects the user can reach') and implicitly scopes it against siblings like list_branches and list_builds, which operate on a project rather than the project list. An agent can distinguish this tool without opening any 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?

Gives an explicit ordering rule: 'Call it first: every other tool takes a project by its name.' This tells the agent exactly when this tool is required relative to every sibling tool, which is the only routing decision that matters for a discovery/list call.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive already cover safety), the description adds real operational context: request bounds (seven, or ten without `kind`), line limits (default 100, max 500), the one-mebibyte read window, the 65536-byte JSON cap, and truncation signaling. It also carries a prompt-injection warning that `untrusted_lines` are third-party output to be treated as data, which the annotations cannot convey.

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 content is dense but front-loaded with the core purpose, then organized into clear Return, Touch, and Bounds blocks. Every clause carries information, though the prose is wordier than strictly necessary for the bounds figures.

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 filtered-read tool with 6 params, 0% schema coverage, and an output schema, the description fills every gap an agent needs: default log selection, filtering semantics, hard limits, truncation, and the security caveat on returned lines. Nothing required to call it correctly 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 description coverage is 0%, so the description must compensate, and it does for the non-obvious parameters: `kind` defaults to install/odoo, `contains` matches literally rather than as a pattern, and `lines` defaults to 100 with a 500 cap. `project`, `branch`, and `build_id` semantics are largely self-evident and only lightly addressed.

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 the last lines of a log of a build of a branch of a project') and immediately scopes it to a specific build number or the latest. It also defines the default log selection (install if present, otherwise odoo) and the `contains` filter, so an agent can distinguish this read tool from `get_build` and `wait_for_build` without opening 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?

It clearly explains selection conditions: without `kind` you get install-then-odoo, `build_id` selects a specific build versus latest, and `contains` filters literally (explicitly not a pattern). No sibling is named as an alternative, which keeps it from a 5, but usage conditions are otherwise explicit.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses exact request and size bounds (seven requests, 1024-byte headers, 50 attachments, 32768 bytes of body, 16 MiB cap), truncation behavior, and that HTML bodies arrive as text and nothing is opened. It also warns that returned fields are untrusted data and must not be followed as instructions.

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?

Front-loads the core action and packs bounds, security notes, and return shape efficiently. The opening clause is slightly convoluted, and the Returns/Bounds sections partly duplicate the output schema, but every line remains informative.

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 four parameters and an existing output schema, the description supplies the missing parameter semantics, safety guidance, truncation and size limits, and untrusted-data handling. An agent has everything needed to invoke it correctly.

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?

With 0% schema coverage the description must carry parameter meaning, and it explains mail_id's origin, build_id's semantics (specific number or the latest), and implies project/branch via the build scoping. Project and branch themselves are not explicitly described, leaving a small gap.

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 (read) and resource (one mail), scopes it to a build of a development/staging branch, and ties the id to the sibling tool list_mails, so it is clearly distinguishable from list_mails.

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?

Tells the agent where the id comes from (list_mails) and clarifies that build_id selects a specific build or defaults to the latest, which is clear usage context. It stops short of stating when not to use it or naming other alternatives beyond list_mails.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds substantial behavior: timeout defaults and hard cap (30/50, longer when Odoo.sh is slow), request budget (six requests, one socket, one request every 3 seconds while waiting on a commit), and the `timeout_capped` outcome. This is well beyond what annotations provide.

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 and there is no filler, but the opening sentence is a dense run-on ('the build of that number, or the latest one... the build of that commit, once the branch has one') that forces re-reading. The value is there; the structure could be substantially tightened.

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?

An output schema exists, so return fields need not be restated, yet the description usefully adds the polling/interruption contract (finished=false, next_step, timeout_capped). Bounds and rate-limit behavior are covered. Minor gaps around the project/branch parameters and the build_id-vs-latest ambiguity keep it from a 5.

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 carry parameter meaning, and it largely does: `timeout` (30 default, 50 max), `commit` (first 7-64 digits of a hash, selected once the branch has a build), and `build_id` (a specific build number or the latest). `project` and `branch` are left undifferentiated, keeping it from a 5.

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 up front: waiting for a build of a branch/project to finish, bounded by a timeout, with commit/build_id variants. It is clearly distinguishable from the read-only siblings get_build/list_builds by its blocking/polling semantics, though it never names an alternative tool.

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?

It gives a concrete usage scenario ('give it right after a push, when the latest build is still the previous one') and clarifies the polling contract: an unfinished build is not an error, `finished` is false, and `next_step` instructs the agent to call again. It stops short of explicitly contrasting with get_build or stating when not to use it.

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