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

No annotations are provided, so the description carries the full burden. It discloses a genuine behavioral constraint: the path must resolve inside UPLOAD_DIR (default /shared/uploads) and paths outside are refused, plus the mutual exclusion of file_path and base64_data. However, it omits Odoo-side permission/auth requirements, size limits, and whether this creates a new ir.attachment record or overwrites existing ones, which matters for a mutation tool with zero annotation coverage.

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 purpose in one line, then uses a tight two-bullet structure for the modes; no filler sentences. There is minor redundancy with the schema's UPLOAD_DIR constraint, but repeating a security-critical constraint in the description is defensible.

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?

Both input modes, the cross-tool routing to prepare_upload, and the directory jail are covered, and an output schema exists so return values need no explanation. The remaining gap is behavioral, not structural: auth requirements and write-side effects go unmentioned for a mutation tool with no annotations.

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 the schema already documents every parameter, including the mutual exclusivity of file_path and base64_data and the res_id/res_model dependency. The description restates the mode semantics but adds no syntax or value format beyond the schema, so the baseline of 3 is correct.

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 ('Upload a file attachment to Odoo via ir.attachment') and immediately enumerates the two supported input modes, so the agent knows exactly what the tool does. The distinction from sibling create_record is implicit in the attachment-only scope, and the prepare_upload reference further locates it in the toolset.

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 explicit mode-selection rules: use file_path when the file lives on the MCP server, base64_data when the file is not on disk (with a concrete example, 'image uploaded via Discord'). It names the alternative tool (prepare_upload) and the exact condition that selects it (remote server, client-side file), leaving nothing 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 and idempotentHint, so safety is covered. The description adds essentially nothing beyond that: it does not say what happens when domain is omitted (the null default), whether counting is bounded or expensive on large models, or how the count is returned.

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?

A single clause with zero filler, front-loading the verb and resource. It is arguably terse to the point of under-specification, which keeps it from 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?

With an output schema present, return values need not be explained, and annotations cover the safety profile. What is missing is the default behavior when domain is null (count everything) and any cost/performance caveat, which matters for a count over arbitrary models.

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%, including extensive domain examples and the operator list, so the schema carries the full parameter burden. The description only restates that the domain filters, adding no syntax or format detail beyond the schema. 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 ('Count records in an Odoo model') plus the filtering mechanism ('matching the domain'), so the operation is unambiguous. It does not explicitly contrast itself with search_records or read_records, which is where it loses a point.

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 use this instead of the many sibling read tools (search_records, read_records), nor any prerequisite or exclusion. The agent must infer that this is the cheap alternative when only a number is needed.

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?

No annotations are provided, so the description bears the full behavioral burden. It never states required permissions, whether created records can be rolled back, how validation errors from Odoo constraints surface, or what a partial batch failure does — significant gaps for a mutation tool.

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?

A single short sentence with no padding, and the verb/resource are front-loaded. It is efficient, though the brevity reflects under-specification rather than disciplined economy.

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 explained. However, with zero annotations and a write operation, the description should disclose at least side effects, permission needs, or batch error behavior; it discloses none of these.

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 'model' and 'values' both documented in the schema (including the batch list option), so the baseline is 3. The description adds nothing beyond restating 'record(s)' and 'model', which the schema already covers more precisely.

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 ('Create') and resource ('record(s) in an Odoo model'), making the operation immediately identifiable. It does not explicitly differentiate itself from siblings like update_record or delete_record, but the name/verb pairing is unambiguous enough for selection.

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 no when-to-use guidance: no mention of choosing create_record over update_record, no context on when to batch-create versus single-create, and no prerequisites. The '(s)' hints batch capability but does not say when to use 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 already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description adds the irreversibility emphasis and, more importantly, the two-phase confirmation workflow that the annotations do not encode. It stops short of noting Odoo access-right requirements or cascade/error behavior, so it is not fully exhaustive.

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 and risk in one line, then the operational rule in the following lines. Every sentence carries a distinct constraint (what it does, that it cannot be undone, how to sequence the calls) with 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?

An output schema exists so return values need not be described, and annotations carry the destructive/idempotent profile. Combined with the fully documented 3-parameter schema, the description supplies exactly the missing piece an agent needs: the confirm-before-delete workflow.

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 the schema already documents ids, model and the confirm safety flag, giving a baseline of 3. The description adds meaning by attaching hard ordering semantics to confirm (False first, True only after approval), which constrains how the parameter must be used in a sequence rather than just what it stores.

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 ('Delete records from an Odoo model') and immediately flags the operation as IRREVERSIBLE, which cleanly separates it from create_record and update_record in the sibling set. An agent can identify the 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, mandatory protocol: call with confirm=False first, set confirm=True only after explicit user approval, never on the first call. This is unambiguous when-to-use guidance with exclusions ('NEVER') rather than soft suggestion.

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 destructiveHint=true annotation by naming concrete dangerous methods (action_confirm, action_post, button_validate, toggle_active), disclosing that state changes can be irreversible, and warning explicitly that the server does NOT guard these calls. That is exactly the context an agent needs beyond structured fields.

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 in the first sentence, followed immediately by the safety warning. No filler; every sentence carries weight for a dangerous tool.

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 no explanation, and destructiveHint covers the safety profile. Combined with the explicit warning about unguarded business methods, an agent has everything needed to decide whether and how to call this.

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, method, args, and kwargs are already documented in the schema. The description adds no format, ordering, or shape guidance for args/kwargs, so the 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 (execute) and resource (method on an Odoo model) and self-classifies as a 'general-purpose escape hatch,' which cleanly distinguishes it from the CRUD-specific siblings like create_record, update_record, and delete_record.

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 a clear precondition: 'Before calling any method that changes state, make sure the user explicitly asked for it.' This gives real when-to-use guidance, but it never routes the agent to the dedicated siblings (e.g. use update_record for standard writes) or states when this escape hatch is appropriate for reads.

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 idempotentHint=true, so the safety profile is covered. The description adds no behavioral context beyond the ORM method name – nothing about metadata vs data, cost, or what happens with an unknown model. With annotations doing the heavy lifting it is not misleading, but it adds little.

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?

A single front-loaded sentence with no filler. The trailing ORM implementation reference is arguably the least useful part but is not wasteful enough to penalize heavily.

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 explained. For a simple read-only metadata tool the description is minimally adequate, but it omits any guidance on filtering versus returning all fields – a distinction the description could clarify beyond the schema defaults.

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 4 well-documented params (model, fields, attributes, field_filter), so the schema already carries full parameter meaning. The description contributes nothing additional about parameters, making the baseline 3 correct.

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 (get) and resource (field information for an Odoo model), and names the underlying ORM call (fields_get()). An agent can tell it retrieves schema/metadata rather than record data. It does not explicitly contrast with list_models, so it stops short of 5.

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 use this tool versus list_models, read_records, or execute_method. No prerequisites, no when-not conditions, no mention of alternatives. Usage is left 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 idempotentHint=true, covering the safety profile. The description adds no behavioral context beyond restating the basic operation—it does not mention scope (e.g., whether custom models are included), pagination, or return volume, so it contributes little beyond the structured fields.

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 wasted words. While extremely brief, it is appropriately sized for a simple listing tool, though it could be slightly more informative without becoming verbose.

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 simple complexity, rich annotations, and an output schema, the description's minimal statement is barely adequate. It covers the core purpose but leaves usage relative to siblings and filtering behavior unaddressed, so it is just the minimum viable.

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 the single optional parameter (name_filter) is fully documented in the schema with an example. The description does not mention filtering at all, which is acceptable given the schema's completeness, resulting in the baseline score of 3.

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 ('Odoo models'), making the tool's purpose immediately clear. However, it does not differentiate from sibling tools like get_fields or execute_method, which also interact with Odoo metadata.

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 provides no guidance on when to use this tool versus alternatives such as get_fields or search_records. It omits any context, prerequisites, or exclusions, leaving usage 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?

No annotations, so the description carries the full burden and does: it discloses that a short-lived upload_token is issued, that the upload endpoint is <origin>/upload via multipart field 'file', that auth is a Bearer header, and even the response shape ({file_path, file_name}). This is exactly the behavioral context needed for a credential-issuing tool.

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 sentence followed by a numbered workflow. The curl example and one-line JSON response are dense, useful payload rather than padding; every sentence 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?

For a zero-param, token-issuing tool with a sibling chain, the description supplies endpoint construction, auth, request format, expected response, and the next tool to call. Nothing an agent needs to execute the workflow 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?

Zero parameters, so the baseline is 4. The description adds the semantics of what the tool yields (endpoint info + token) and how to consume it, which schema alone cannot express.

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+resource ('Prepare an out-of-band upload of a CLIENT-side file to this server') with the scope narrowed to client-side files on a remote server. It clearly distinguishes itself from add_attachment, which it routes to as the follow-up step.

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?

Explicit when-to-use ('when the file to attach lives on the client machine and this MCP server is remote') and names the avoided alternative (base64_data in the token stream) with the reason. No inference required.

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 readOnlyHint and idempotentHint annotations already establish the safety profile, and the description is consistent with them. However it adds no behavioral context beyond the annotations — nothing about behavior for non-existent/duplicate IDs, missing models, or the field-exclusion default that the schema mentions.

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?

A single front-loaded sentence with zero filler or repetition. It is arguably too terse for a tool with three parameters, but it is not padded, so structure and brevity are good.

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-value details need not be explained, and the schema fully documents the inputs. Still, this read tool sits among search_records and list_models without any routing guidance, leaving the agent to work out which read variant to pick.

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 all three parameters (ids, model, fields) are already self-documented in the schema, including the dangerous-field auto-exclusion behavior of fields. The description adds no parameter-level detail beyond restating that lookup is by ID, so the 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 plus resource plus the selection mechanism ("Read specific records by their IDs"), which implicitly separates it from the batched search_records sibling. It never names the alternative tool explicitly, so differentiation still requires inference from the sibling list.

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 their IDs" implies the precondition for using this tool (you already have IDs) versus searching, but there is no explicit when-to-use/when-not statement and no mention of search_records as the alternative path. Usage is inferable rather than stated.

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 idempotentHint=true, so safety is covered, but the description adds nothing on top: no note on pagination semantics (limit/offset interaction), no mention that unset fields auto-exclude binary/html, no return-shape context. For a search tool with real behavioral quirks, this is a bare minimum.

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?

A single short sentence with no padding and nothing buried; it is front-loaded. It is efficient rather than wasteful, though the brevity reflects under-specification that the other dimensions already penalize.

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 explained, and all six parameters are documented in the schema. The remaining gap is contextual: no hint of Odoo domain usage or how this relates to the eight sibling record tools, which a description for a search entry point should at least gesture at.

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 the domain/order/fields parameters are documented in the schema with examples, so the schema does the heavy lifting. The description adds no parameter meaning beyond that, which lands at the baseline 3.

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 verb (Search) and a resource (records in an Odoo model), so the basic purpose is legible. However, it is so terse that it fails to separate this tool from close siblings like read_records, count_records, or list_models, leaving the agent to guess at scope.

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 guidance at all: nothing says to pick this over read_records or count_records, no mention of the domain-based filtering that is the tool's distinguishing feature, and no preconditions. The agent gets no routing help.

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 idempotentHint=true, so the description carries most of the behavioral burden. It says 'existing records', hinting that nonexistent IDs are not created, but says nothing about batch semantics, partial failure behavior, or required access rights for a mutation tool.

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?

A single short sentence with the verb and resource front-loaded and no wasted words. It is efficient, though its brevity is partly the same under-specification captured in other dimensions.

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 generic Odoo write tool with nested values and no destructive/read-only annotation, the description leaves out error behavior, permission needs, and return expectations. The presence of an output schema removes the need to describe return values, but the behavioral gaps remain.

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. The description adds no format or constraint detail beyond what the schema provides, making the baseline 3 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?

The description states a specific verb and resource (update existing records) and names the domain (Odoo model), so it is clearly distinguishable from create_record, delete_record, and read_records by verb alone. It does not explicitly contrast itself with those siblings, but the verb is unambiguous.

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 use this tool versus alternatives such as create_record or execute_method, and no prerequisites (permissions, valid model names) are mentioned. The agent must infer usage entirely from the verb.

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