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

Beyond the readOnly/destructive annotations, the description discloses important runtime behavior: it may return best null on empty or thin input, never invents a setup, returns qualitative fit labels plus playbook text, and the catalog direction label should be ignored. This is meaningful behavioral 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 dense but mostly earns its length: it front-loads the optional-hint warning, then gives eligibility rules and output caveats. However, it is a single wall of text; structured bullets or shorter sentence groups would make the guidance easier to scan and apply.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a nested vision_features object, the description compensates well by covering null results, output labels/playbook, the direction-label caveat, and gate rules. The main omission is the exact return container shape (single best match vs list), especially because max_results suggests multiple candidates may be returned.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by linking timeframes to actual read intervals and TICK/Fan eligibility, tying groups_read to fetched groups and the vol-gated setup #78, and explaining that vision_features includes raw_vision_text with natural language and negation handling. Max_results relies on the schema, which already describes it well.

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 specific action and resource: cross-checking vision_features against the 64-setup active library. It also explicitly contrasts itself with the client-driven matching and with maatsii_get_setup, so an agent can distinguish it from siblings without extra digging.

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 opens by marking itself as an optional hint and telling the agent not to lead with it, which is direct usage guidance. It also states when extra parameters are required (timeframes for TICK eligibility, groups_read for setup #78) and names the verification sibling maatsii_get_setup.

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