data_completeness

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral rule beyond that: blank text counts as missing. However it says nothing about how nulls vs empty strings vs whitespace are treated further, or what happens for a nonexistent field name. Given the read-only annotations cover the risky dimensions, a 3 is fair.

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

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

The purpose is front-loaded in the first sentence with the key rule (blank text equals missing) in parentheses, followed by a compact Args list. The Args list partially duplicates schema titles, but with 0% schema description coverage that duplication is earning 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?

An output schema exists, so the return shape does not need explaining, and the description already states what the result measures (filled, missing, distinct counts). For a 3-parameter read-only inspection tool this is close to complete; only edge-case behavior for invalid paths or fields is 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 description coverage is 0%, so the description must carry the parameters, and it does explain all three: path is the vector layer to inspect, fields is an optional subset defaulting to all fields, and layer selects a layer inside a multi-layer file. It does not specify accepted path formats or what error surfaces for an invalid field name, which keeps it below 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 names the specific measurement (filled/missing values per field plus distinct-value counts) and its scope (attributes of a vector layer), which clearly separates it from siblings like layer_info or area_by_stratum. It is not a bare restatement of the name 'data_completeness' because it enumerates exactly what is counted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose (a data-quality check on a layer's attributes) but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to the sibling tools such as layer_info that also describe a layer. An agent can infer the context but must decide on its own.

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