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

The description reveals behavior beyond the sparse annotations: content does not pass through the AI, the link is ephemeral, single-use, and valid for 30 minutes, and the user must open it to drop files. It also explains what status returns, which is valuable operational context not captured elsewhere.

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 dense and informative, with the core constraint front-loaded. It is slightly long and runs multiple instructions together, but every sentence carries necessary information and there is little fluff.

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 7 parameters spend a bare schema and an output schema present, the description covers the main workflow and guardrails well. It omits explicit semantics for upload_id and journal_id, which could leave an agent unsure how to complete the status polling or journal-specific invoice upload.

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 description coverage, the description compensates well by explaining action values, named file slots, purpose='invoice' for OCR, and model+res_id for attaching to existing records. However, upload_id and journal_id are left unexplained; upload_id in particular seems important for the status action, so the compensation is not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends files into Odoo via an ephemeral upload linkache and gives concrete use cases like invoices, contracts, and justificatifs. It distinguishes the link flow from raw base64 arguments but does not explicitly contrast sibling tools such as aidoo_create or aidoo_document, so sibling differentiation is only 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 provides explicit when and when-not guidance: 'NEVER put base64 or raw file content in tool arguments — always use this link flow.' It also prescribes the exact flow: request_upload first, give the URL to the user, then use status to retrieve IDs, with conditional guidance for purpose='invoice' versus model+res_id.

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 description adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations: the mandatory two-call lifecycle, the data it returns, and the environment-fixity rule. There is no contradiction with the readOnlyHint, as the tool is described as context-loading rather than mutating.

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 detailed but every sentence earns its place: the mandatory call pattern, parameter meanings, call timing, and the environment-switch exception are all operationally necessary. The most important rule is front-loaded in the first sentence.

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?

The description is fully complete for a lifecycle tool: it specifies when to call, what to pass, what comes back, and what not to do. The presence of an output schema means return values do not need further elaboration.

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%, but the description fully defines both parameters: 'prompt' is the user's original question for the first call, and 'response' is the final answer summary for the last call. This compensates completely for the schema's lack of 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?

The description clearly states what the tool does: it loads session context, returning identity, permissions, priority models, and Odoo URL, and is used at the start and end of a conversation. It also differentiates itself from the many sibling aidoo_* tools by explicitly declaring it must be called before any other aidoo_* 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?

The description is exceptionally explicit about when to call this tool: exactly twice per conversation, first with 'prompt' and last with 'response'. It also gives clear when-not guidance, including not calling it before each tool and not re-checking a changed Odoo environment.

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 indicate a non-read-only, non-idempotent operation. The description adds the requirement for confirmation, which is a behavioral trait not captured in the annotations. It does not contradict any annotations and provides useful 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?

The description is two sentences with no fluff. It front-loads the core purpose and then gives concise usage and confirmation details. Every word 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?

While the description covers the main creation modes and confirmation, it leaves ambiguity about how 'confirmed' is used (does the agent need to set it true?) and what happens if both 'values' and 'values_list' are provided. The output schema exists but is not shown; given the tool's complexity, more detail on parameter interplay would improve completeness.

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 description coverage, the description must compensate. It explains the roles of 'values' and 'values_list' and alludes to 'confirmed' via 'Requires confirmation', but it does not detail the 'model' parameter or clarify the relationship/mutual exclusivity between 'values' and 'values_list'. Partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create one or multiple records in an Odoo model' with a specific verb and resource, and distinguishes between single and batch creation via 'values' and 'values_list'. It is immediately distinguishable from sibling tools like aidoo_read, aidoo_write, and aidoo_delete.

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 clear parameter-level guidance ('Use values for a single record, or values_list for batch creation') and mentions the confirmation requirement. However, it does not explicitly name alternatives or state when not to use this tool, though the create vs. write/delete distinction is implied.

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 description goes beyond the destructiveHint annotation by emphasizing that deletion is PERMANENT and IRREVERSIBLE with no undo, and by requiring confirmation (confirmed=true). It also discloses the need to provide 'model' and 'ids'. This adds meaningful behavioral context that the annotation alone does not convey, such as the irreversibility and the confirmation requirement.

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 compact and front-loaded with the most critical information (permanence, irreversibility) before the operational details. Every sentence earns its place: the warning, the required parameters, the confirmation requirement, and the alternative routing. 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?

Given the tool's destructive nature, the description covers all essential context: what it does, what is required, the confirmation flag, and the safer alternative. The output schema exists, so return values need not be described. The description is complete enough for an agent to decide when and how to invoke this tool 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 description coverage is 0%, so the description must compensate. It does mention 'model' and 'ids' and the confirmation flag, which covers the key parameters. However, it doesn't explain the exact format of 'ids' (array of integers) or the default behavior when ids is null, but the schema already provides that structure. The description adds the semantic meaning that these parameters are required for a permanent delete operation, which is valuable.

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 ('PERMANENTLY delete'), the resource ('records from an Odoo model'), and the underlying operation ('unlink'). It clearly distinguishes itself from the sibling aidoo_write by explicitly recommending archiving via active=False when deletion is not truly intended. This is a precise, unambiguous purpose statement.

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 explicitly says when to use this tool (when permanently deleting records) and when NOT to use it (when the user only wants to hide records, prefer aidoo_write with active=False). It also names the alternative tool directly. This is exactly the kind of routing guidance an agent needs.

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 mark the call as read-only and idempotent, and the description adds valuable non-obvious behavior: credit pricing per 20 pages with a 30-page max, one-time charging per document, async status queries, and the notable warning that returned content is document data, not instructions. This goes well beyond the annotation hints.

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 dense but every clause earns its place: formats, analysis output, targeting modes, action variants, pricing, limits, and a security warning. It is front-loaded with the primary purpose and then branches into modes without repeating schema facts.

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 complex 9-parameter tool with no schema coverage, the description covers all primary invocation strategies, action semantics, async handling, and cost constraints. The output schema exists and annotations cover safety, so the description does not need to restate return values; the only small omission is the optional field parameter, which does not undermine completeness.

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. It clearly explains attachment_id, document_id, model+res_id, filename, action, question, and job_id, adding meaning such as the 'free when already read' condition. The field parameter is never mentioned, leaving one of nine parameters undocumented.

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'), resource ('Odoo attachment'), supported formats (PDF/image/scan/Word), and what the agent gets (transcription + structured analysis). The vision-model qualifier in the title and the three-action behavior make it clearly distinguishable from generic siblings.

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 guidance on when to use extract vs ask vs status, including the free-after-read condition and the async situation for long documents. It also explains which target parameter combination to use (attachment_id, document_id, or model+res_id), though it does not explicitly contrast the tool with aidoo_read or other sibling tools.

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 declare destructiveHint=true and readOnlyHint=false, which properly signal the tool can modify data. The description adds one behavioral fact: 'Requires confirmation' – implying the agent must set the 'confirmed' parameter to true explicitly. This is useful and goes beyond the annotation. However, it doesn't describe what happens if confirmed is false (does it error? return a confirmation request?), what side effects the method may have, or whether the method is executed in a transaction. With annotations covering the destructive nature, a 3 is fair: adds some value but leaves important behavior opaque.

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 brief—two short sentences. It's front-loaded with the core purpose and includes a critical behavioral hint (confirmation). No wasted words. However, given the complexity of a generic method executor, this brevity borders on under-specification, but it's still concise and to the point.

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?

The tool has 5 parameters, an output schema, and destructive annotations. The description is far too thin to fully equip an agent. It doesn't explain the confirmation flow (how to interpret a false 'confirmed' response), what kind of output to expect, or any restrictions on method names (e.g., should only call methods that are safe?). The output schema exists but the description doesn't guide interpretation. Compared to sibling tools like aidoo_create or aidoo_write which have richer descriptions, this one leaves too much to inference.

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% – the parameter names (model, method, args, kwargs, confirmed) are present in the schema but have no descriptions. The tool description provides zero explanation of what each parameter means. For instance, 'confirmed' is a boolean that likely must be true to execute, but the description doesn't state that clearly beyond 'Requires confirmation.' The agent must infer that 'confirmed' gates execution. Similarly, 'args' and 'kwargs' are self-explanatory to an Odoo expert but not explicitly tied to the method call. The description fails to compensate for the 0% schema coverage.

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 clear verb and resource: 'Execute a custom method on an Odoo model.' This distinguishes it from generic CRUD tools like aidoo_create or aidoo_write, which handle standard methods, whereas this executes arbitrary custom methods. However, it doesn't specify what kind of custom methods (e.g., business logic, complex operations) or contrast with aidoo_workflow_run, which might also trigger custom logic. Overall, purpose is clear but slightly under-specified.

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 almost no guidance on when to use this tool versus alternatives. It doesn't mention that aidoo_create/aidoo_write/aidoo_delete should be preferred for standard CRUD, nor does it warn against using it for read-only custom methods (which might be better via aidoo_query/aidoo_read). The 'Requires confirmation' hint is present but not expanded; there's no explanation of when confirmation is needed or how to approach it. No explicit exclusions or context for selection.

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 declare destructiveHint=true, so the agent knows this is a destructive operation. The description adds context by explaining the tool is for integrating user corrections into the hint, and that it should be called with the full updated hint. This goes beyond the annotations by clarifying the intended use case and the expected input format. However, it doesn't detail what exactly gets destroyed (the previous hint) or any irreversible consequences, but the annotation covers the destructive nature.

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 two sentences, front-loaded with the core purpose, and every sentence earns its place. The first sentence states what the tool does, the second explains when and how to use it. 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?

Given the tool has only 2 parameters, an output schema, and annotations covering destructive behavior, the description is fairly complete. It explains the purpose, the trigger (user correction), and the expected input (full updated hint). The only minor gap is not explicitly stating what the output schema contains, but the output schema exists and the description needn't explain return values. The description is adequate for an agent to select and invoke the tool 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 description coverage is 0%, so the description must compensate. The description mentions 'model' and 'updated_hint' implicitly: 'for an Odoo model' and 'call this tool with the full updated hint'. This adds some meaning beyond the bare schema, but it doesn't fully explain what 'model' refers to (e.g., the model name string) or what 'updated_hint' should contain beyond 'full updated hint'. The description partially compensates but leaves some ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: updating AI instructions (hint) for an Odoo model based on user feedback. It specifies the verb 'update', the resource 'AI instructions (hint) for an Odoo model', and the context 'based on user feedback'. This distinguishes it from sibling tools like aidoo_write or aidoo_create, which are generic CRUD operations.

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 explicit guidance on when to use this tool: 'When the user corrects a result or points out an error'. It also describes the workflow: reformulate the existing hint to integrate the correction, then call this tool with the full updated hint. This is clear and actionable, though it doesn't explicitly name alternatives, the context is specific enough to avoid confusion with siblings.

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 convey idempotency and non-destructiveness, lowering the burden on the description. The description adds useful behavioral details: it returns a download URL, supports specific models, and accepts custom report names. It does not disclose potential side effects, permissions, or failure modes, but given the annotations, this is an acceptable but not rich disclosure.

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 with no filler. The core action is front-loaded, followed by the return type, supported models, and the optional parameter behavior. Every sentence contributes useful 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?

The description, combined with the output schema and annotations, covers the main purpose, return behavior, and some parameter semantics. Still, it does not mention how the ids parameter should be interpreted or provide any example invocation, and it gives no guidance for handling unsupported models. This is workable but not fully complete for a tool with 0% schema description coverage.

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 does add meaning for 'model' by listing common supported models and for 'report_name' by explaining custom report support. However, it leaves the required 'ids' parameter essentially unexplained beyond the schema's type and title, which is a clear gap for a required parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Generate a PDF report for Odoo records' and adds a concrete output behavior ('Returns a download URL'). It is much more informative than the title, but it does not explicitly distinguish itself from the sibling tool 'aidoo_report', so it misses the sibling-differentiation element of a 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?

The description implies its usage context by focusing on Odoo records and enumerating supported models (sale.order, account.move, purchase.order, stock.picking). It also gives guidance for the optional report_name parameter. However, it never says when to prefer this tool over sibling alternatives like aidoo_report or aidoo_document, leaving selection partly 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 mark the tool read-only and idempotent, and the description adds valuable behavioral context beyond that: results are paginated with a default of 80, pagination info is returned, and callers must handle next_offset to retrieve all records. This fully discloses the tool's 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?

The description is compact and every sentence earns its place: purpose, pagination behavior, sorting, and the critical pagination warning. Important operational details are front-loaded and clearly flagged with 'WARNING'.

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 annotations, schema, and presence of an output schema, the description covers what an agent needs to select and invoke the tool correctly. It explains the default limit, how to paginate through all results, when to prefer aidoo_report, and how sorting works, leaving no critical gap for this read-only query 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?

The schema has no per-parameter descriptions (0% coverage), so the description carries the burden. It adds meaning to key parameters: 'domain filter' explains domain, 'order' is tied to sorting, and offset/limit behavior is explained through pagination and looping. It does not fully describe domain syntax or the fields parameter, so it stops short of 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 action ('Search and read records') on a specific resource ('an Odoo model') with an explicit filtering mechanism ('domain filter'). It also distinguishes itself from aidoo_report by directing statistical or aggregation use cases there. This is clear and actionable.

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 explicitly says when to avoid this tool ('For statistics or aggregations, use aidoo_report instead') and gives concrete pagination guidance for when all records are needed ('MUST loop with offset=next_offset while has_more=true'). This is strong, explicit usage direction.

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, and the description is consistent with them. It does not add behavioral context beyond those annotations, such as field-selection side effects or behavior on missing records, but the annotations cover the core safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler or redundancy. It is concise while still naming the action, target, and primary input.

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 tool with three parameters, zero schema-level descriptions, and several sibling tools, this description is too thin. It does not explain the required 'model' parameter, the optional 'fields' behavior, or the distinction from query/search tools. The existing annotations and output schema reduce but do not eliminate this 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 0%, so the description must compensate by explaining parameters. It only mentions IDs and does not describe what 'model' means, what format fields expects, or how the optional fields parameter behaves. This leaves the agent dependent on underspecified 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 clear verb and resource: 'Read specific Odoo records by their IDs.' It conveys exactly what the tool does and implies the core input (IDs), though it does not explicitly differentiate itself from sibling tools like aidoo_query.

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 gives no guidance on when to use this tool versus alternatives, such as when to prefer aidoo_query for searching or filtered reads. No exclusions or decision criteria are provided.

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; the description adds a meaningful behavioral trait beyond that, namely that it processes ALL matching records server-side with no pagination limit. No contradictions with annotations.

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 with the key scoping and alternative-use guidance front-loaded; no wasted wording.

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?

The description is fit for selection and safety context given the annotations and output schema, but the complete absence of parameter-level documentation leaves gaps around what measure/group_by accept and how the domain is expressed. Adequate overall, with clear gaps.

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% and the description does not explain the semantics of the required parameters (model, group_by, measure) or the domain array. It names the action and mentions grouping conceptually, but an agent still lacks guidance on valid measure strings, domain syntax, or group_by entries.

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 names a precise operation ('Run an aggregation (read_group) query on an Odoo model') and explicitly separates it from aidoo_query, so an agent can identify it 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 gives direct selection guidance: 'PREFERRED tool for statistics, totals, counts, averages, and any analysis' and says to use it instead of aidoo_query for stats. This is explicit when-to-use guidance with an alternative 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the 'exposed' qualifier and the conditional behavior based on the model parameter, which is useful, but it does not disclose anything beyond what the annotations plus the simple binary behavior imply.

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 sentence that front-loads the action and clearly presents the two modes with no wasted words. It is compact and immediately scannable.

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 is a read-only schema inspector with only one optional parameter, annotations covering safety and idempotency, and an output schema defining return values, the description is sufficient for correct invocation. Minor omissions like model name format are not critical for this simple 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 must carry parameter meaning. It does explain that providing a model returns field definitions and omitting it lists models, but it does not specify the expected model name format (e.g., 'res.partner' vs 'res_partner') or explicitly state null behavior.

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 action on a specific resource: listing exposed Odoo models or returning field definitions for a given model. It clearly distinguishes this from data-manipulation siblings like aidoo_create and aidoo_write, though it does not explicitly name an alternative.

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 through the two modes described: call without model to list models, or with model to get field definitions. However, there is no explicit guidance on when to prefer this over aidoo_query or aidoo_read, nor any exclusions or 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?

Annotations already declare destructiveHint=true, so the tool is known to be destructive. The description adds 'Requires confirmation' which is useful, but it does not explain what 'confirmation' means (e.g., user prompt or a confirmation parameter), what the destructive effect is, or whether changes are reversible. For a destructive mutation tool with no additional annotation context, this is insufficient.

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 concise, a single sentence, and starts with the main purpose. It avoids extraneous information. It could be structured slightly better by front-loading the confirmation requirement, but overall it is efficient.

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?

The tool has a complex purpose (workflow actions on Odoo) with no parameter documentation and no behavioral detail beyond the annotation. The output schema exists, so return values are not needed, but the description still omits critical usage context like the meaning of 'confirmed' and the destructive side-effects. It is not complete enough for an agent to call it correctly without external knowledge.

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%, and the description does not describe any of the four parameters. The schema provides basic names and types, but no meaning (e.g., what 'model' values are valid, what 'action' options exist, and how 'confirmed' relates to the confirmation requirement). The description must compensate for this gap, but it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Execute') and resource ('business workflow action on Odoo records') with a concrete example ('confirm a sale order'). It is distinct from sibling tools like aidoo_workflow_run, but does not explicitly differentiate itself from similar workflow tools.

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 guidance on when to use this tool versus siblings like aidoo_workflow_run or aidoo_workflow_list. The example gives a hint of typical use, but it does not state when not to use it (e.g., read-only operations should use aidoo_read).

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 useful context beyond the annotations: it lists only user-saved Aidoo templates, not Odoo automations, and specifies the intended call order after aidoo_context. It does not discuss empty results or pagination, but the output schema likely covers return shape.

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: when to call, what it lists, and what it is not. The key instruction is front-loaded, and there is no filler or redundant restating of the title.

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 zero parameters, an output schema present, and read-only/idempotent annotations, the description covers call placement, trigger conditions, and data scope. Nothing essential for selecting or invoking this tool 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?

The tool has zero parameters, so the description has nothing further to add about parameter syntax or meaning. Schema coverage is trivially 100%, and the description's phrase 'all workflow templates' clarifies the implicit scope of the empty argument list. Baseline 4 is appropriate 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?

The description uses a specific verb ('Lists'), a concrete resource ('all workflow templates saved by the user in Aidoo'), and explicitly scopes it to Aidoo, not Odoo. It clearly differentiates the tool from Odoo's ir.actions and base.automation, making its purpose 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?

It explicitly instructs to call the tool 'right after aidoo_context' and states the trigger condition: when a user asks to run a workflow or task they saved before. It also gives a clear exclusion by saying the answer is not found in Odoo's ir.actions or base.automation, giving strong 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 mark destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context by stating the tool 'Requires confirmation' and that it injects variable values, which are not present in annotations. No contradiction exists between description and annotations.

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 two sentences with no filler. It front-loads the core action and then adds usage sequencing and a safety note. 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?

Given that an output schema exists, the description does not need to explain return values. It covers purpose, usage sequence, and confirmation. It could mention how to obtain the slug (implied via the list tool) or give more detail on variable injection, but overall it is sufficient for a 3-parameter tool with annotations and an 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?

With schema description coverage at 0%, the description must compensate, and it does: 'slug name' clarifies workflow_name, 'injecting variable values' clarifies the variables parameter, and 'Requires confirmation' implies the confirmed boolean. It could be more explicit about the variables object structure, but it adds meaningful semantics beyond the bare 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?

The description states a specific verb ('Execute') and resource ('saved Aidoo workflow template') and explains the mechanism ('by its slug name, injecting variable values'). It references a related sibling (aidoo_workflow_list) but does not explicitly contrast itself with aidoo_execute, so it is clear but not fully differentiated from all siblings.

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 explicit sequencing guidance: 'Use after finding a match from aidoo_workflow_list.' It also notes the prerequisite that confirmation is required. However, it does not state when not to use this tool or name alternative tools for different scenarios, so it stops short of a full when/when-not guide.

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 mark this as destructive (destructiveHint: true), but the description adds a valuable behavioral detail: 'Requires confirmation.' It also indicates that the operation targets existing records, reinforcing the mutation semantics. This goes beyond what annotations alone provide, justifying a score above baseline.

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 with no redundancy. The main purpose is front-loaded, followed by concise usage instructions and the confirmation requirement. 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?

With an output schema present and annotations covering destructive behavior, the description covers the essential aspects: purpose, primary usage modes, and confirmation. It does not discuss prerequisites, error cases, or edge cases, but these are less critical given the output schema and simple required parameter ('model'). Slightly incomplete for a write operation, but adequate for the complexity.

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 of explaining parameters. It explains the roles of 'ids' and 'values' for single updates, and 'batch' for multiple updates, and implies 'confirmed' via 'Requires confirmation.' It does not detail the exact structure of batch items, but it adds substantial meaning beyond the raw 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?

The description clearly states the tool updates existing records in an Odoo model, using a specific verb and resource. It differentiates from siblings like aidoo_create and aidoo_delete by emphasizing 'existing records,' though it does not explicitly name alternative tools.

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 clear internal guidance on when to use 'ids'+'values' (single update) versus 'batch' (multiple updates), which is helpful. However, it does not explicitly contrast this tool with sibling tools or state when to choose aidoo_write over aidoo_create or aidoo_update (though such a tool does not appear in siblings). The usage context is implied but not fully spelled out.

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