Odoo MCP by bancada

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description still adds real value by noting it makes no Odoo backend call and that it returns a text message, both beyond what the annotations state.

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?

Two tight sentences with the core measurement front-loaded and the no-Odoo clarification following. No wasted words.

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 no parameters, an output schema, and read-only annotations, little explanation is needed. The description covers what is measured, the time window, and that it avoids Odoo, leaving only minor detail like text-message format already covered by the output schema.

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 to document and the baseline is 4. No parameter detail is expected or missing here.

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 measurement (connector calls used and remaining) over a defined window (rolling 30 days) for a specific scope (the account's company). The 'Does not call Odoo' clause distinguishes it from all the odoo_* siblings at a glance.

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 'Does not call Odoo' note implicitly separates it from the sibling Odoo tools, but there is no explicit when-to-use guidance or stated alternatives. An agent can infer it's a usage/quota check but is not told when to reach for 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?

Annotations only declare readOnlyHint=false / destructiveHint=false, which is confusing for an operation that mutates a pending action's state. The description resolves that ambiguity by asserting nothing is executed in Odoo and that a confirmation message is returned — genuinely additive context. It stops short of saying whether a discarded code can be recovered or what happens on an invalid/expired code.

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?

Three short sentences, each carrying distinct information: what is discarded, that no Odoo data is touched, and what is returned. The key guarantee (nothing executed) is front-loaded, and there is no filler.

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 single-parameter tool with a full schema and an output schema, the definition covers action, side-effect boundary, and return type. The only gap is failure semantics for an invalid or already-discarded code, which an agent would want before calling blind.

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 100% and the schema already says 'Six-character pending-action code to discard'. The description's 'identified by its code' only restates this, adding no format, sourcing, or lifecycle detail. Baseline 3 applies when the schema does all the work.

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 ('Discards') and resource ('the pending write identified by its code'), and the sentence 'Nothing is executed in Odoo' makes the contrast with odoo_confirm/odoo_execute unmistakable. An agent can tell this is the negative counterpart of confirm without reading 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?

Usage is implied rather than stated: an agent can infer this is the 'abort' path, but the description never names odoo_confirm as the alternative or says 'use this when you want to abandon a staged write'. No explicit when/when-not, so 3 rather than 4-5.

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 destructiveHint=true and readOnlyHint=false, and the description goes beyond them by disclosing the code lifecycle: single-use, 30-minute expiry, and binding to the originating account and connection. It also enumerates failure outcomes (unknown, expired, already used, other connection), which is exactly the behavioral context an agent needs before invoking a destructive write.

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?

Two sentences, front-loaded with the action and followed by constraints and return shape. Every clause carries information; nothing is redundant with the annotations or schema.

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 tool with an output schema and destructive annotations, this is sufficient: it covers lifecycle, failure modes, and what the response contains. Nothing an agent needs to call it safely 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 100%, so baseline is 3, but the description adds real semantics the schema lacks: the code is single-use, time-limited, and connection-bound, which changes how an agent should source and reuse it. The only gap is that the six-character format itself lives in the schema, not here, which is acceptable.

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: 'Executes the pending write identified by its code.' That is clearly distinct from odoo_read/odoo_write, though the description never names the nearest siblings (odoo_execute for direct execution, odoo_cancel for discarding a pending action), so the agent must infer the boundary.

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 rather than stated: a code 'returned by a write tool' must be confirmed here. It does not explicitly route the agent to odoo_cancel when the action should be abandoned, nor contrast this with odoo_execute, which is the most likely confusion point given the sibling list.

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 (readOnlyHint=false, destructiveHint=false), the description discloses a non-obvious behavior: in write-confirmation mode nothing is created and a pending-action code is returned instead of a record. It does not cover permission requirements or validation-failure behavior, but the pending-action disclosure is genuinely valuable context the annotations lack.

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?

Two short sentences with the core action and return shape front-loaded, followed by the conditional edge case. No filler and every sentence adds value.

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 mutation tool, the description covers the action, the return shape, and the important write-confirmation branch, with annotations and an output schema filling in safety and return details. It is nearly complete, though it omits access/permission requirements.

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% for both required parameters (model, values), and the description adds no additional semantics about them. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 ('Creates a record in an Odoo model') and describes the return payload. It is separable from siblings like odoo_write/odoo_unlink by implication, but never names a sibling or the model/record scope explicitly.

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 verb 'create'; there is no explicit when-to-use guidance, no mention of when to prefer odoo_write or odoo_execute, and no prerequisites noted. The write-confirmation aside hints at a condition but does not route the agent to an alternative.

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=false and destructiveHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the return envelope (model, method, result) and, importantly, the pending-action code path when write confirmation is enabled, which the agent could not infer from structured fields. It stops short of stating permission requirements or irreversibility of arbitrary method calls.

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?

Two tight paragraphs, front-loaded with what the tool does, followed by a distinct and non-redundant note on the pending-action outcome. No filler sentences, though the return-value sentence slightly duplicates the output schema.

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 and annotations cover the destructive profile, lowering the burden. Still, for a tool that can invoke any method on any model, the description omits the critical routing guidance against the many specialized siblings and any constraints on which models/methods are permitted, leaving a meaningful gap.

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% and already documents args as positional, kwargs as keyword, and method with an example. The description restates the positional/keyword distinction but adds no new semantics such as how args map to Odoo's RPC signature or how kwargs interact with named parameters. Baseline 3 is appropriate.

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?

Names a specific verb and resource ('Calls a method of an Odoo model') and gives concrete examples (posting an invoice, confirming a sales order) so the agent knows this is a generic method-invocation escape hatch. However, it never differentiates itself from close siblings such as odoo_confirm, odoo_write, or odoo_create, and its own examples overlap with those siblings' territory.

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?

No statement of when to reach for this generic executor versus the purpose-built siblings (odoo_confirm, odoo_cancel, odoo_write, odoo_create). The examples given actually point toward sibling use cases rather than routing the agent away from them, leaving the choice entirely to inference.

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=true and destructiveHint=false, so the safety profile is covered. The description adds the shape of the payload (model, field_count, fields) beyond what annotations provide, but says nothing about auth requirements, cost on large models, or whether the call is cached.

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?

Two short sentences, front-loaded with what is returned. The second sentence partly restates the first's enumeration but stays within a reasonable length 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?

For a simple read-only two-parameter inspection tool with a full output schema, the description covers what the tool returns and its scope. The missing piece is guidance on when to reach for odoo_list_models first, which would round it out.

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 100%, so both parameters are already documented, giving a baseline of 3. The description's field list (type, label, required, relation, selection) does not quite match the schema's documented default attributes, which includes readonly and omits label, so it adds no reliable meaning beyond the schema and slightly muddies it.

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: returns field definitions of an Odoo model, with the metadata it yields enumerated. It is distinguishable from odoo_list_models and odoo_read by being field-level inspection, but the description never names those siblings to make the distinction explicit.

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?

There is no when-to-use or when-not-to-use guidance, and no mention of the obvious alternative (odoo_list_models) for discovering models versus inspecting one model's fields. The agent must infer the selection rule from the names 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?

The annotations already establish that this is a read-only, non-destructive operation, and the description adds relevant behavioral context: restricted accounts see only allowed models, and users who cannot read the catalog get a fallback set of common readable models. It also discloses the return shape as JSON with count and models (model, name).

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 three sentences and front-loads the main purpose before adding scope and return details. Every sentence contributes useful information with no wasted text.

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 simplicity, full schema description coverage, and the existence of an output schema, the description is complete enough for an agent to call it correctly. It covers the core purpose, optional filter, restricted-scope behavior, fallback behavior, and return format.

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%, so both parameters are already documented in the schema. The description reiterates the filter's purpose against technical name or label, but it does not add syntax or behavioral detail beyond what the schema already provides.

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 gives a specific verb and resource: it lists the models available in the Odoo database, with optional filtering by technical name or label. This makes the tool's purpose clear, though it does not explicitly differentiate itself from sibling tools such as odoo_fields_get or odoo_search_read.

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 usage by explaining that results can be optionally filtered by technical name or label, and it notes restricted-scope behavior. However, it does not explicitly state when to use this tool instead of alternatives like odoo_fields_get or odoo_search_read, nor does it provide exclusions.

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=true and destructiveHint=false, so the safety profile is covered. The description adds only a brief return-format note, which duplicates the output schema, and says nothing about behavior for missing/invalid IDs.

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?

Two short sentences with no filler, and the operation is stated first. It is efficient, though it spends one of only two sentences restating the return shape already covered by the output schema.

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 annotations, full schema coverage, and an output schema, the lightweight description is close to adequate. Still missing is any note on error behavior for nonexistent IDs or guidance on selecting this tool over the search siblings.

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 each of the three parameters documented, so the schema carries the load. The description adds no extra meaning about the fields parameter or ID semantics beyond what is already structured.

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 ('Reads Odoo records by ID'), which clearly distinguishes a by-ID fetch from search-style siblings. It does not, however, explicitly name odoo_search_read or odoo_search_count as the alternatives, so differentiation is implicit.

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 says nothing about when to use this versus odoo_search_read, odoo_search_count, or odoo_fields_get. An agent must infer from the name that this is the right tool only when IDs are already known.

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=true and destructiveHint=false, so the safety profile is covered. The description adds that no records are returned and that the response contains model and count, but the latter is largely duplicated by the existing output schema, so added behavioral value is modest.

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?

Two short sentences with zero padding, and the non-returning behavior is front-loaded where an agent will see it first.

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 annotations, a full output schema, and 100% schema description coverage, the description supplies enough for correct invocation. A brief note on domain syntax or typical use against odoo_search_read would close the remaining gap.

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 100% and the schema itself explains that an empty domain counts all records. The description adds no domain syntax or filtering semantics beyond what the schema already provides, so baseline 3 applies.

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 ('Counts the records of an Odoo model that match a domain') with the key modifier 'without returning them', which implicitly separates it from odoo_search_read. It stops short of naming a sibling, so differentiation is inferred rather than explicit.

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?

'Without returning them' implies the use case (need a number, not the records) but there is no explicit when-to-use/when-not statement or named alternative such as odoo_search_read versus odoo_search_count. Usage is left to inference.

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=true and destructiveHint=false, so the safety profile is covered structurally. The description adds only the 'single request' efficiency note and a restatement of the return shape, which the output schema already supplies; no mention of pagination behavior or the default 50-record cap's practical effect.

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?

Two sentences, front-loaded with the action and scope, with no filler. Every sentence adds information and nothing is repeated unnecessarily.

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 annotations covering safety, a fully described schema, and an output schema explaining the return shape, the description is nearly sufficient. The one remaining gap is routing guidance against odoo_read and odoo_search_count for an agent choosing among them.

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 limit, model, order, domain, fields and offset all documented in the schema including examples. The description only echoes 'domain filter', so baseline 3 applies — the schema carries the parameter burden.

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: searches an Odoo model with a domain filter and reads matching records in one request. This is clearly distinguishable from a read-by-id tool or a count-only tool, though it never names those siblings explicitly.

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 'in a single request' implies this is the combined search+read path rather than search-then-read, but no explicit when-to-use guidance or exclusion against odoo_read or odoo_search_count is given. Usage must be inferred from the sibling names.

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=false and destructiveHint=true, yet the description adds genuinely new behavior: the write-confirmation gate can turn a delete into a no-op returning a pending-action code. That is exactly the kind of side-effect an agent needs to know. It stops short of saying what happens to related records or how partial failures are reported.

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?

Two sentences, no filler, with the permanence warning and the return shape front-loaded before the conditional confirmation behavior.

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?

Output schema exists so return values need not be explained, and annotations carry the safety profile. The description closes the remaining meaningful gap by disclosing the confirmation-gated non-deletion path. Only edge-case behavior on errors or record dependencies is left unaddressed.

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 100% and both parameters (ids, model) are documented in the schema, so the baseline of 3 applies. The description adds nothing about batch semantics, model naming format, or what happens with invalid ids.

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 ('Permanently deletes Odoo records') and adds the permanence qualifier, which separates it from reversible mutations like odoo_write. It does not name a sibling explicitly, so differentiation is inferred rather than stated.

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?

There is no guidance on when to choose this over odoo_write, odoo_cancel or odoo_confirm, nor any prerequisites such as required model access. Usage context is only implied by the tool name and the destructive framing.

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=false and destructiveHint=true, so the destructive nature is covered structurally. The description adds genuinely non-obvious context beyond that: the return shape (model, ids, updated) and, importantly, that when write confirmation is enabled nothing is actually changed and a pending-action code comes back instead. It still omits what happens on partial/invalid field sets and whether the update is atomic, which keeps it below 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?

Two tight sentences ordered by importance: what it does first, the confirmation-mode caveat second. No filler, no restatement of the title, and the surprising behavior is surfaced rather than buried.

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 only light treatment and the description supplies the key nuance about the pending-action variant. For a destructive mutation on a nested, free-form 'values' object, it would be stronger if it warned about invalid field names or required write access, but the essentials for correct invocation are present.

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%, so 'model', 'ids' and 'values' are already documented in the schema, establishing the baseline of 3. The description only says 'with the given field values', adding no format, validation, or model-specific detail beyond what the schema already conveys.

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: 'Updates existing Odoo records with the given field values.' The verb 'updates' cleanly separates it from odoo_create and odoo_unlink in the sibling list, though no sibling is named explicitly.

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 word 'existing' – an agent can infer this is for modifying records that already have IDs rather than creating them. There is no explicit when-to-use/when-not guidance, no mention of odoo_create as the alternative for new records, and no prerequisites such as required permissions on the target model.

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