Tukey

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is low, but the description adds real context beyond them: the profile is derived from public videos or Reels only, YouTube profiles include subscriber and video counts, and the tool is explicitly not an analytics source for per-video views, last-video performance, or Instagram reach. That capability-boundary disclosure is exactly what prevents misinvocation.

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?

It is front-loaded with the core constraint ('only to read the user's own already-connected account') before the enumerations and exclusions. It runs long and repeats the 'not other people's channels' exclusion twice (once mid-text, once at the end), which costs some economy without adding information.

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?

There is no output schema, and the description compensates by describing the return payload (Tukey's profile with content pillars, formats, voice, hooks, audience, subscriber/video counts) and its data provenance. For a zero-parameter tool, nothing an agent needs in order to call it correctly or avoid calling it is missing.

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 tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. The description implicitly clarifies that the target account is fixed by the authenticated user's connection in Tukey, which is the only 'parameter-like' semantic that matters here.

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 precise verb+resource+scope: read the user's OWN already-connected YouTube channel or public Instagram account, and states what the tool returns (Tukey's profile built from public videos/Reels, with subscriber and video counts). It explicitly distinguishes itself from identifying or comparing other creators' accounts, so an agent can separate it from siblings without opening a 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?

It gives explicit when-to-use triggers (content pillars, formats, recurring series, voice, hooks, audience, subscriber/video counts, or pre-planning context for titling/pitching a video or Reel) and explicit when-NOT-to-use cases (someone else's channel, general YouTube/Instagram advice, per-video analytics, Instagram reach/audience data). It also names the alternative behavior for identification tasks ('look those up elsewhere').

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add operational context. It usefully discloses the return payload structure (community, title, link, dated) and the hard dependency on a prior tool call. It does not mention pagination or result caps, which keeps it just under a 5.

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: trigger intent first, return shape second, constraint last. No filler, and the routing constraint is front-loaded where an agent will see it before invoking.

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 a single required parameter, rich annotations, and no output schema, the description covers everything needed: what triggers it, what the input must be, and what it returns. Nothing material is omitted for a tool of this complexity.

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 100% and the parameter's own description already states it is 'The `id` of an idea returned by list_video_opportunities.' The description restates the same provenance rule, adding emphasis but no new semantic detail about the identifier itself. Baseline 3 applies when the schema fully carries parameter meaning.

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 names a specific verb+resource combination ('returns its dated source citations') and anchors it to a concrete user intent ('why Tukey suggested a specific idea'). It also implicitly separates this retrieval tool from the sibling that produces ideas (list_video_opportunities).

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 an explicit trigger condition (user asks why / wants sources / wants community posts), a prerequisite (an id from list_video_opportunities), and a prohibition ('Do not use it without an id from that tool'). The alternative path is spelled out rather than inferred.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context on top: the return payload is identity only, with no channel data or analytics, and there is a call-ordering constraint relative to sibling tools. It does not need to describe fields because an output schema exists.

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 positive purpose is front-loaded, which is good, but the body stacks negations and repeats itself: the channel/Instagram exclusion is stated twice ("This is not the profile of the connected YouTube channel or Instagram account" and later "another creator's channel or account"). Nearly every sentence is a prohibition, so the signal-to-noise ratio could be improved by consolidating them.

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 trivial, zero-parameter identity lookup with an output schema, the description supplies everything needed: trigger condition, sibling alternatives, ordering, and payload limits. Nothing material is missing.

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 tool takes zero parameters, so there is nothing for the description to clarify beyond what the empty schema shows; the baseline for a no-param tool applies. The description correctly implies no input is needed to identify the caller.

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: "Return the connected Tukey login identity." It immediately disambiguates from the near-named sibling get_channel_profile by declaring it is not the YouTube channel or Instagram account profile, so an agent can route correctly without opening a 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?

Gives an explicit triggering condition (only when the user explicitly asks which Tukey login or email is connected) plus named alternatives and the ordering rule that get_channel_profile, list_video_opportunities and get_opportunity_evidence already resolve the authenticated account. It also enumerates exclusions: video performance, other creators' accounts, general YouTube/Instagram questions.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the burden is lighter; the description adds return-shape and grouping detail plus the default-false shortlist behavior. It does not cover pagination, result counts, or what 'evidence' means (left to get_opportunity_evidence), which keeps it short of a 5.

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?

Usage guidance is front-loaded before the return description and the negative cases are collected at the end, which is good structure. The sentences are long and somewhat repetitive about 'their own channel or account', which costs a point but nothing is truly extraneous.

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?

There is no output schema, and the description compensates by describing the returned idea record and its grouping, so an agent knows what it will get. Combined with explicit exclusions and a single optional parameter, nothing an agent needs to call this correctly is missing.

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 single parameter include_saved is fully documented in the schema (100% coverage) including its default, and the description does not restate or extend it. With schema coverage this high, the baseline of 3 is appropriate.

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 names a specific resource (current video/Reel ideas for the creator's own channel) and enumerates the returned fields: working title, premise, angle, hook, channel fit, why now, evidence strength, grouped as timely/evergreen/early-watch. It clearly separates itself from siblings like rate_video_opportunity and start_video_opportunity, which act on an existing idea rather than generating a list.

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?

Explicit routing is given in both directions: use it for 'what to make next', idea lists, content plans, or hook/title requests with no topic; do not use it when a topic is already supplied, for generic brainstorming, scripts from scratch, competitor channels, or analytics. It also names the preference ('prefer this over inventing ideas'), leaving little to inference.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), it discloses the actual semantics: it updates or replaces the existing saved rating, the latest rating wins, and a reject temporarily suppresses the idea and its topic. It also scopes the blast radius by stating it only touches private Tukey state and never publishes, deletes, or modifies YouTube or Instagram content — valuable context given the destructive flag. It stops short of covering error behavior or how long the temporary suppression lasts.

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?

It is front-loaded with the trigger and the rating options, then moves to side effects and exclusions. It is slightly long and restates the enum meanings already present in the schema, but every sentence still carries routing or behavioral information.

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 two-parameter mutation with no output schema, the description covers trigger, allowed values, state effects, scope limits, and the relevant sibling alternative. The only gap is what happens with an invalid or unknown opportunity_id, which is minor here.

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 100% and both parameters already document the enum meanings and the uuid format in detail, so the schema carries the weight. The description adds only the provenance hint that the id comes from list_video_opportunities, which is a marginal addition; baseline 3 is appropriate.

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 names a specific verb (rate/save/pass/dismiss) and resource (a Tukey video idea) and enumerates the three rating outcomes, so an agent can distinguish it from siblings like start_video_opportunity or list_video_opportunities without opening a 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?

It gives explicit trigger conditions ('when the user reacts to one of their Tukey video ideas') plus negative guidance: do not use it to start work on an idea (use start_video_opportunity), and do not rate an idea the user has not reacted to. Both alternatives and exclusions are stated.

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

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

Beyond the annotations it discloses the seeding behavior, that a workspace link is returned, and repeat-call idempotency at the semantic level ('returns the same workspace and never creates a second one'). It does not explain the destructive aspect flagged by destructiveHint=true — nothing in the description tells the agent what could be overwritten or what permissions/account state are required.

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: trigger first, mechanics and return value second, exclusions last. No filler, and every clause (seeding, idempotency, save behavior) carries distinct information.

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 one-parameter mutating action with full annotation coverage and no output schema, the description covers trigger, source of the ID, side effects, return value, and repeat-call behavior. The remaining gap is the destructiveHint=true aspect, which is never addressed in prose.

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 100% and the single parameter is fully described, so the baseline is 3. The description adds provenance the schema lacks by tying the opportunity_id to list_video_opportunities, telling the agent where the value must come from.

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 gives a specific verb and resource ('opens the idea's video workspace ... seeded with the idea's own pitch') and states exactly what input it consumes and what it produces. It is clearly distinguishable from siblings like list_video_opportunities and rate_video_opportunity, which are named.

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 states the triggering condition ('when the user decides to make one of their Tukey video ideas'), names the alternative for the adjacent case ('do not use it merely to save an idea (use rate_video_opportunity with keep)'), and excludes unchosen ideas. Both when-to-use and when-not-to-use are explicit.

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