add_drive_file_comment

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

Annotations indicate this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that the comment is 'attached directly to the file,' implying it's not a reply. However, it does not mention any side effects like permissions or idempotency (idempotentHint=false), which would be useful. No contradiction with annotations.

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 very concise (two sentences, 14 words) and front-loaded with the core purpose. It wastes no words, but could benefit from a brief usage tip or reference to the 'not' constraint already in the schema. Still, it is efficient and clear.

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?

Given the tool has 4 parameters (2 required) and an output schema exists, the description is minimally adequate. It explains the main action and the locator constraint but omits the output (likely the created comment object) and does not mention non-idempotency (multiple calls create multiple comments). Annotations cover safety but not usage details. Overall, it covers the essentials but leaves gaps.

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?

The input schema has 100% coverage but only trivial descriptions ('a string that will be trimmed'). The description adds meaning: it clarifies that the body is a Markdown comment and explains the exclusive relationship between filePath and fileId ('Provide only one locator'). This adds some value beyond the schema, but not enough to raise the score above the baseline of 3.

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 states the action ('Add a Markdown comment to a Drive file') and the resource ('Drive file'). It specifies the two locator options (filePath or fileId) and the constraint to provide only one. This distinguishes it from other add_* tools, though it does not explicitly differentiate from similar tools like add_comment.

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 provides a key usage rule ('Provide only one locator') but does not explain when to use this tool versus alternatives (e.g., add_comment for other contexts). No prerequisites or postconditions are mentioned, leaving the agent to infer the appropriate use case.

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