set_hyperlink

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

There are no annotations, so the description carries the full behavioral burden. It discloses that the operation overwrites existing links, enforces exactly one destination, and saves atomically with a two-slot backup and an opt-out via 'backup=False skips rotation'. This is strong transparency for a mutating tool.

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 economical: the core action is front-loaded, followed by target semantics, destination rules, and persistence behavior. The 'delete_slide knows how to neuter' aside is a bit cryptic, and the insert_shape pairing is tangential, but overall the text earns its length for the tool's complexity.

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?

For a mutation tool with no annotations and seven parameters, the description covers the nontrivial parts: target resolution, unique destination, tooltip, and atomic backup. It correctly relies on the output schema for return details. A small gap remains around the expected format for file_path and slide, which prevents a 5.

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?

With 0% schema description coverage, the description compensates by explaining target's shape-id vs text-range forms, to_slide's index or slide_id object format, tooltip semantics, and backup behavior. It leaves file_path and slide formats implicit, but those are more inferable from the tool context.

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 opens with a specific verb and resource: 'Set a hyperlink on a shape or text range'. It also states the operation replaces any existing link, which immediately differentiates it from siblings like remove_hyperlink and list_hyperlinks.

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 gives clear routing context: 'Exactly one destination: url (external) or to_slide (a jump by index...)'. It also mentions how navigation buttons pair with insert_shape, helping the agent understand related tool use. It does not explicitly contrast with remove_hyperlink or list_hyperlinks, so it falls short of full when-not-to-use guidance.

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