check_odoo_addon_health

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

With no annotations, the description carries the full disclosure burden. The word 'static' usefully signals that no code is executed and that this is a read-only inspection, but it says nothing about whether files are touched, whether external services or a live Odoo instance are needed, or how long a full audit takes. It also does not describe the shape of the result (issue list, severity levels, pass/fail), which is important for a 'health' 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?

The description is front-loaded: the scope sentence comes first, followed by a clean Args block. It has no filler sentences. The opening sentence is long but still earns its place by enumerating the audited surfaces.

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 two-parameter, annotation-free tool with no output schema, the description covers the inputs well but is silent about the return value. That matters for a 'comprehensive audit' whose usefulness depends on whether it returns structured findings, counts, or prose. It also does not mention any limits or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does: addon_path is described as an absolute or relative path to the addon directory, and addons_directories is described as an optional list of directories containing other addons, used to resolve module dependencies. The dependency-resolution purpose of the second parameter is genuine added meaning. It does not specify what a relative path is relative to, which is a small gap.

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

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

The description gives a specific verb ('Run a comprehensive static health audit') and resource (an entire Odoo addon directory), then enumerates the five areas checked (manifest, dependencies, XML views, Python models, security rules). This makes clear that the tool is a broad, all-in-one audit, unlike the narrow single-aspect sibling analyzers (validate_odoo_manifest, analyze_odoo_xml_view, analyze_odoo_python_model, analyze_odoo_security). However, the description never states this contrast directly, so an agent must infer it.

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 explicit when/when-not guidance or named alternatives. The enumeration of check areas only implies that this tool should be used when a full audit is needed, rather than calling individual sibling analyzers. There is also no mention of when to prefer verify_odoo_live_metadata, which would cover the dynamic side that this static audit does not.

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