list_hyperlinks

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

No annotations are provided, so the description must carry full disclosure. It clearly states the operation is read-only ('file is never modified'), enumerates the types of hyperlinks included, and describes broken-target detection behavior. This gives an agent a solid safety profile and behavioral expectations without relying on 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?

Three sentences deliver a dense but efficient definition. Every clause earns its place: scope default, included link types, broken-target detection, compatibility with mutation tools, exclusions, and read-only safety. No filler or redundancy.

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 an output schema, the description need not detail return fields. It still covers scope semantics, exclusions, and read-only behavior, which are the main operational unknowns. The complexity is moderate, and the description fully prepares an agent to invoke it correctly, especially alongside the related sibling tools.

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 compensate. It does clarify the 'scope' parameter with 'default all slides', adding meaning beyond the bare schema. The 'file_path' parameter is left implicit, but it is a common and self-evident required string. The description also hints at the semantic coupling between the returned addresses and set_hyperlink/remove_hyperlink, which helps an agent interpret values correctly.

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 states a specific verb-resource pair: lists all hyperlinks in the presentation, covering external URLs and jump-to-slide links on shapes and text runs. It explicitly differentiates itself from siblings by clarifying what is excluded (media playback controls) and by noting relationships to set_hyperlink/remove_hyperlink.

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 conveys when to use the tool: to inspect all hyperlinks in scope, and it notes that the returned addresses are exactly what set_hyperlink and remove_hyperlink accept, implying use for auditing before editing. It also explicitly says media playback controls are excluded, routing users to insert_video/insert_audio instead. However, it does not mention when to prefer this over list_elements or get_text, nor does it provide explicit 'when not to use' guidance beyond the media exclusion.

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