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

Annotations only indicate a write operation that is not destructive. The description adds meaningful behavior: fields are soft-verified after writing, mismatches are logged rather than failed, and the request is rejected if no metadata field is provided. This goes beyond the annotations and helps an agent predict failure modes.

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 compact and front-loaded: purpose first, then verification behavior, then the required-field constraint. Every sentence contributes useful information, and the [category: pdf] tag is unobtrusive.

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?

The full definition—description plus schema—covers the core invocation needs well: required file, field semantics, inability to blank fields, and password-protected input handling. There is no output schema, so return-value details are not fully specified, but the soft-verification behavior gives enough expectation for normal use.

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 100%, so the parameters are already well documented. The description adds the at-least-one constraint and lists the writable fields, but it does not provide significant meaning beyond what the schema already states about empty values, clearing behavior, or password-protected input.

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 clearly identifies a specific action and resource: writing or updating metadata fields (Title, Author, Subject, Keywords) in a PDF. It is distinguishable from siblings like pdf_get_metadata and pdf_remove_metadata, and the explicit field list removes ambiguity about what the tool does.

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 description implies when to use the tool through its name and 'Write or update metadata' phrasing, but it does not explicitly name alternatives or exclusions in the main description. The schema does mention using pdf_remove_metadata for clearing fields, but the description itself relies on inference rather than direct routing.

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