inspect_hidden_data

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

Annotations already declare readOnlyHint, idempotentHint and closed-world, so "Changes nothing" is largely redundant. The genuinely additive content is the password handling: the "ask" sentinel means the secret is typed on a local page and never passes through the chat, which is a real behavioral fact an agent cannot learn from annotations or schema. Notably, it also implies the tool reports incremental-update remnants rather than just current metadata.

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, both earning their place: the first front-loads scope via a single dense enumeration, the second handles the one non-obvious parameter behavior. No filler, and the operation's consequence-free nature is stated up front.

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 return structure need not be explained, and the enumerated categories line up with what the report contains. With only one substantive parameter beyond a self-explanatory required path, and that parameter's special value documented, nothing an agent needs to invoke it 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the password parameter only partially — the "ask" sentinel value is documented, but null/omitted behavior (i.e. what happens for encrypted files when no password is given) and the input_path parameter are unaddressed, though the latter is self-evident from its name and required status.

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?

Specific verb ("Report") plus a precisely bounded resource (hidden data a PDF carries), followed by an explicit enumeration: metadata, scripts and risky actions, attachments, comments, application data, thumbnails, and earlier saved versions. That enumeration is what separates it from the sibling subset tools like get_metadata, list_attachments, and list_comments, so an agent can pick the right one without opening a 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?

"before sharing it" supplies a clear situational trigger, which is the main use context an agent needs. It stops short of explicit exclusions or naming alternatives (e.g. use get_metadata when only author/software is wanted), so it is clear context without routing rules.

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