Read one YouTube item

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered structurally. The description adds behavior the annotations cannot express: full content plus metadata are returned, and an inaccessible id surfaces as an error or null rather than a mismatched item. This is genuinely additive, though return shape and pagination remain unstated.

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 short sentences, each carrying distinct information: what it does, the read-only/full-content contract, and the failure semantics. The identifier-flow constraint is front-loaded with no filler.

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 single-parameter read tool with no output schema, the description covers identity, safety and the null/error edge case well. It leaves the return structure undefined (only 'full content and metadata'), which would be worth spelling out given there is no output schema to fall back on.

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% and the schema already says the id is the native id 'exactly as returned by the matching connector_<id>_search result'. The description repeats that same constraint with no added syntax, format, or validation detail, so the baseline 3 applies.

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 and resource (read one YouTube item), names the exact source of the identifier (connector_youtube_search), and is trivially distinguishable from its sibling connector_youtube_search. An agent can pick between search and fetch without opening either schema.

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?

Explicitly ties usage to a preceding search call ('by the id returned from connector_youtube_search'), which establishes the required workflow order. It does not state when not to use it or name any alternative fetch path, so it stops short of a 5.

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