Green Screen Memes

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is fully covered. The description's only added behavior is that results come back "in order" and that "trending" is a valid synthetic id — useful but thin beyond what the schema states.

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?

Two short sentences, front-loaded with the resource and scope, with the special-id note last. Nothing 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?

A simple read tool with full annotation coverage and fully documented parameters; the description plus schema is sufficient to invoke it correctly. Only the relationship to the overlapping get_trending sibling is left unaddressed.

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%, including the "trending" special value, so the description adds no meaning beyond the schema. Baseline 3 is appropriate; the "trending" sentence merely restates the id parameter's schema description.

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 green screens in one collection" states the resource and scope precisely, and "in order" adds a meaningful property. It's a noun phrase rather than a verb, and it doesn't distinguish itself from sibling get_trending despite sharing the "trending" concept.

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 only guidance is a parameter hint (use id "trending" for trending clips), which is usage of an argument, not when to choose this tool over get_trending, list_collections, or get_green_screen. No exclusions or alternatives are named.

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 this as a safe, idempotent, read-only lookup, so the description doesn't need to cover safety. What it does add is the payload: the clip's video link plus an ffmpeg recipe for compositing over an image or video, which tells the agent what practical follow-up the result enables.

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?

One front-loaded sentence with no filler; the resource, the lookup key, and the return content all appear in a single clause chain.

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 no output schema it is appropriate that the description sketches the response (video link, ffmpeg recipe). For a one-parameter read tool with full annotation coverage, that is close to complete, missing only guidance on failure or missing-id behavior.

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?

There is a single parameter at 100% schema coverage, and the schema already says it is 'The id from search results'. The description adds nothing about the id format or source beyond that, so 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?

The description names a specific verb and resource ('One green screen clip by id') and its scope of return ('video link and an ffmpeg recipe'). It implicitly contrasts with the list/search siblings by saying 'one ... by id', though it never names search_green_screens explicitly.

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?

Usage is only implied: the schema note 'The id from search results' hints this follows a search, but the description itself gives no when-to-use or when-not-to-use guidance versus search_green_screens or get_collection.

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, non-destructive and closed-world, so the safety profile needs no restatement. The description adds genuinely new behavioral information beyond annotations: results are popularity-ordered, each clip carries a trending rank, and the remaining fields match search results.

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?

Two short sentences with zero filler, and the most important fact (what the feed contains and its ordering) is front-loaded.

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 no output schema, the description usefully explains the return shape (rank plus the standard search-result fields) and the sort order. The one gap is that the trending window behind 'right now' is never defined, which matters for a trending endpoint, but otherwise it is sufficient to call the tool correctly.

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?

Both parameters are fully documented in the schema (limit with default and max, cursor as nextCursor for paging), so the schema carries the semantics. The description adds nothing about limit or cursor behavior, which is acceptable given 100% coverage but earns only baseline credit.

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 the resource (trending green screen clips in the Green Screen Memes app) and the ordering (most popular first, rank 1 = most popular). It is clearly a distinct feed from search_green_screens, though the verb is carried mainly by the title rather than the description text.

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 phrase 'what people are using right now' implies this is the tool for discovering popular content rather than querying by keyword, but it never names search_green_screens or states an explicit condition for choosing between them. Usage is implied, not spelled out.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's job is to add scope. It does: the data is scoped to the calling API key, limited to the current month, and covers two specific metrics (calls and video downloads), which no annotation conveys. It stops short of saying whether values are counts, limits, or percentages, and says nothing about caching or quota-window boundaries.

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?

One short sentence, zero filler, with the scope (this API key) and the time window (this month) front-loaded. Nothing could be removed without losing scope 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?

With no output schema, the description must carry the return-value burden, and it does name the three things returned: plan, call usage, and video-download usage. Given a zero-parameter, low-complexity tool this is close to sufficient, though it leaves the shape of those values (raw counts vs. limits vs. remaining quota) unstated.

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 no schema semantics for the description to compensate for; baseline for a no-param tool is 4. The description appropriately devotes no words to parameters.

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 the exact resource (this API key's plan and month-to-date call and video-download consumption), which is specific enough to distinguish it from every sibling (get_collection, get_trending, get_green_screen, etc.). It omits an explicit retrieval verb — 'Get' only appears in the name/title — so it reads as a return-value sketch rather than a stated action, which keeps it out of the top band.

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?

There is no explicit when-to-use or when-not-to-use statement and no alternative tool is named. The scope words 'this month's calls and video downloads' do imply the natural use case (checking quota/plan before or after heavy usage), but the agent must infer that rather than being told.

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 fully covered and the description correctly doesn't restate it. What it adds is modest: that collections are 'curated' and that 'trending' is a live, usage-driven collection. It doesn't say whether the set is fixed or how fresh the trending data is, which is the kind of detail the low openWorldHint invites.

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?

One sentence, no filler, with the resource description front-loaded and the sibling reference trailing as a parenthetical. The nested parentheses ("trending" inside a parenthetical explanation) make it slightly harder to parse than it needs to be, but nothing is wasted.

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 no input parameters and no output schema, the description is the only place an agent can learn what comes back — and it doesn't say whether the result is names, IDs, or objects, or how those feed into get_collection. For a simple zero-arg list tool this is a moderate but real gap; the annotations cover the rest.

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 no parameter semantics to explain and the baseline of 4 applies. The description neither invents nor misrepresents arguments.

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 is a noun phrase identifying the resource ("curated collections of green screens") but never states a verb such as 'lists' or 'returns' — the tool name and title carry that load. It does usefully name one concrete member of the result set ("trending") and points at get_trending, giving partial sibling differentiation, but the core action remains implied.

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 parenthetical routing hint — trending is returned directly by get_trending — tells the agent one case where a sibling is preferable. There is no explicit statement of when to call this tool versus get_collection, list_tags, or search_green_screens, and no prerequisites or exclusions, so guidance is only implied.

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, non-destructive and closed-world, so the safety profile needs no restating. The description does add real behavioral context beyond those: results are the *most used* tags (an implicit ordering) and each carries a green-screen count, which is the kind of shape information annotations cannot express. It omits whether the list is bounded by anything other than limit or what happens beyond the cap.

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?

One short sentence with no filler or redundancy, so it is appropriately sized for a one-parameter read tool. The phrasing 'with how many green screens have each' is grammatically awkward and costs a re-read, which prevents a perfect score.

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?

This is a low-complexity read tool with a fully documented single parameter and rich annotations, so the bar is low, and the description does say what is returned (tags + counts). Still, with no output schema, it should have stated the ordering explicitly and whether counts are exact or approximate, and it leaves the agent unsure what the list looks like beyond the one clause.

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% with a single optional 'limit' parameter documented down to its default of 100, so the baseline is 3. The description contributes indirectly by establishing that results are ranked by usage, which means limit means 'top N by usage' rather than an arbitrary subset, but it never says this explicitly.

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 conveys the resource (tags) and the return payload (each tag plus how many green screens use it, ordered by usage), which is more than a restatement of the name. However, it is written as a noun phrase fragment with no verb and no differentiation from siblings like search_green_screens or get_trending, which could also surface popularity-ranked data. An agent can guess the purpose but must infer the action.

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 only usage signal is the trailing phrase 'to see what the library covers', which implies an exploratory/discovery context but states no when-to-use, when-not-to-use, or alternative tool. Nothing tells the agent whether to prefer this over search_green_screens when its goal is exploring coverage.

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 this as a read-only, idempotent, non-destructive, closed-world search. Beyond that, the description adds the matching semantics (names, tags, descriptions), the empty-query behavior, and which fields come back (ids, names, descriptions, thumbnails, video links) — useful since there is no output schema. It stops short of mentioning pagination or result caps.

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 with zero waste: what it searches, the empty-query behavior, and the return shape — all front-loaded in the first sentence.

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 five-parameter read-only search with full schema coverage and no output schema, the description covers query semantics, default behavior, and return fields. Nothing an agent needs to invoke it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the query is free-form words matched across multiple text fields, and an absent query sorts to newest. It does not discuss tag/color combination behavior, but that is documented per-parameter.

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 — "Search green screen meme clips by words" — and specifies precisely which fields the words are matched against (names, tags, descriptions). This clearly separates it from get_green_screen (single clip) and get_trending (no query), even without naming siblings.

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?

"Leave query empty to get the newest" gives a concrete fallback behavior that guides invocation. There is no explicit routing to alternatives such as get_trending or list_tags when the user's intent is trending or tag browsing, so it falls short of explicit when-not guidance.

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