office_quality_check

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description adds real context beyond them: it enumerates the return payload (file hash, blocking issues, warnings, review units) and warns that machine checks alone do not certify quality, which is a meaningful behavioral caveat about the tool's limits.

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 sentences, front-loaded with the verb, and each carries distinct information: what it validates, what it returns, and its limitation. No filler or restatement of the title/name.

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, the description usefully enumerates the return values and the tool's caveat. Given the highly complex nested contract parameter, it stops short of fully documenting how to construct the contract, but for an agent's core calling decision it is largely complete.

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 50% and the 'contract' parameter is a deeply nested object with no top-level schema description. The description loosely maps its phrasing ('prompt-specific requirements', 'Office package integrity') onto the contract's objective/criteria/baseline structure, but does not explain the contract's sub-fields, tolerance, or forbiddenText/requiredText, so it only partially compensates for the coverage 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?

States a specific verb ('Validate') and resource ('an XLSX, DOCX, or PPTX draft') with the scope of validation (prompt-specific requirements plus Office package integrity). This is clearly distinct from generic inspectors like office_inspect_file, though it does not explicitly name or contrast against office_prepare_review or office_compare_files.

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 line 'Machine checks alone never certify quality' and the promise of 'units requiring visual or analytical review' imply this is a machine pre-check feeding a human/visual review step, but no alternative tool is named and no explicit when-to-use/when-not guidance is given. 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.