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

Annotations already cover safety (readOnlyHint, openWorldHint), and the description adds genuinely new behavioral context: the source is the caption track LinkedIn itself publishes, automatic captions are included, and empty results are not billed. Billing/cost-per-call is the standout detail an agent could not get from structured fields.

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 tight sentences, front-loaded with the purpose then the data source then the edge case and cost. The opening 'Post transcript.' is largely a restatement of the title, but the remainder earns its space.

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?

With only two parameters and no output schema, the description carries the right load: it explains the return shape, the empty-result case, and the cost. The one gap is cache_max_age, which is unexplained in both schema and description.

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 coverage is only 50%: the url parameter is well documented in the schema (post URL, urn:li:activity / ugcPost / share urn, or numeric activity id) but cache_max_age has no description anywhere. The description adds nothing about accepted identifiers or cache behavior, leaving a third of the inputs undocumented.

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?

States a specific verb (retrieve captions) and a precise resource (the caption track of a LinkedIn video post), then defines the output shape as 'one text block plus timed cues'. That framing lets an agent distinguish it from linkedin_post, which returns post metadata/content rather than captions.

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?

It gives clear negative conditions — no video, or a video without a caption track, yields an empty result — plus the cost signal (1 credit, not charged on empty). It never names a sibling alternative such as linkedin_post for non-video posts or linkedin_searchPosts to find posts, so routing is inferred rather than stated.

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