PopOff Data

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

The readOnlyHint annotation already signals a safe read operation, and the description adds meaningful context: the output is CSV text, it matches the web export, and it contains a concrete set of fields. It does not describe edge cases like large results or formatting details, but for a read-only CSV export this is not a significant gap.

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 description is a single dense sentence that front-loads the core output, then efficiently lists the included fields and the return format. Every clause adds information, and there is no filler, misleading prose, or unnecessary repetition.

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-only CSV export, the description covers what the output is, how it relates to the web export, and what data it contains. The absence of an output schema is mostly compensated for by the explicit statement that the response is CSV text. Minor missing details such as headers or pagination do not materially prevent correct usage.

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 'show' is fully documented in the schema itself, including type, example, and a pointer to list_shows for discovery. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate since the structured schema carries the full burden.

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 clearly identifies the resource: citation-ready season cast CSV, and explicitly states it is returned as CSV text. It also names the fields included, which makes it easy to distinguish from sibling tools like get_cast or get_engagement. The title and description together give a direct, specific statement of what the tool produces.

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 'citation-ready' and 'same file as the web export' imply the intended use case, but the description never explicitly tells the agent when to choose this tool over a sibling like get_cast or get_engagement. The input schema does add useful discovery guidance via list_shows, but the description itself depends on inference for choosing this export.

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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful behavioral detail beyond that: it clarifies that time series are summarized as historyPoints counts, so an agent will not expect full underlying series that are available only via get_follower_history. This is especially valuable because there is no output schema.

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 description is front-loaded with the essential phrase 'Full cast of a season' and uses two efficient sentences that make it clear what is returned and when to use an alternative tool. There is no fluff or redundant explanation.

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 adequately inventories the core returned fields and explicitly flags that time series data is summarized. It could mention things like default ordering or response shape, but as a cast listing tool with well-documented parameters, the description is sufficiently complete for correct invocation.

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 input schema already provides 100% coverage with descriptions for all three parameters (show, search, status), so the tool description does not need to re-explain them. The description adds context about the returned data, but not additional meaning for the parameters themselves.

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 and resource: it returns the full cast of a season with concrete data fields such as per-platform follower counts, growth windows, elimination status, and Instagram milestone projections. It also differentiates itself from get_follower_history by noting that time series are merely summarized here.

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 gives clear context: use this tool for a season-wide cast overview with summarized metrics. It explicitly steers the agent to get_follower_history when the full time series is needed. However, it does not directly contrast with all nearby siblings like get_contestant or get_engagement, so the when-to-use guidance is good but not exhaustive.

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?

While the readOnlyHint annotation covers the safety profile, the description adds behavioral context beyond it by explaining the default season behavior and that the result includes the season it belongs to. This is useful and non-obvious information that the schema does not convey.

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 description is two concise sentences with no filler. It front-loads the core action and output, then follows with a clear behavioral note about the optional parameter. Every sentence contributes decision-relevant 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?

Given only 2 parameters with 100% schema coverage, a readOnlyHint annotation, and no nested objects or output schema, this description is complete for an agent to correctly call the tool. The schema covers IDs and discovery, while the description covers selection 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?

The schema already documents both parameters at 100% coverage, but the description adds meaning by clarifying that show is optional and controls season scoping. This extra semantic layer helps an agent understand how to select the right season without opening the detailed schema.

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 clearly states the tool returns one contestant's profile and social metrics, immediately distinguishing it from siblings like get_cast and get_show. It specifies a singular resource and includes the season association, leaving no ambiguity about what is returned.

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 gives direct guidance on when to pass the optional show parameter versus omit it, noting the fallback to the most recent season. It does not explicitly contrast with sibling tools, but the context is clear enough for an agent to know when to call this tool.

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?

The description complements the readOnlyHint annotation by explaining what kind of data is returned: current, baseline, and 30-day history based on likes and comments. It does not describe internal side effects or edge cases, but the annotation already covers the read-only safety profile.

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 description is one concise sentence that leads with the result type, then defines the scopes and metric basis. Every phrase is informative and there is no redundant 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-only tool with no output schema, the description adequately conveys the output dimensions: current, baseline, and 30-day history. It is not overly explicit about response formatting, but the tool is simple enough that this is unlikely to hinder correct invocation.

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 only parameter, contestant, is already documented in the schema with ID or slug examples and 100% coverage. The description adds little beyond restating that the engagement rates belong to a contestant's profiles, so it does not improve on the schema.

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 clearly specifies what is returned: engagement rates for a contestant's profiles, including current, baseline, and 30-day history. It distinguishes from sibling tools by focusing on engagement rates rather than follower counts or events, but it does not explicitly contrast itself with those 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?

The description gives clear context for when to use this tool: when you need engagement rates for a contestant's profile. It does not explicitly state when not to use it or name alternative tools, but the scope is clear enough for a simple 1-parameter read-only lookup.

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 signal read-only, so safety is covered. The description adds useful behavioral context beyond that: data is raw, at approximately 30-minute resolution, and is a follower-count series rather than aggregated or event-based. It doesn't discuss output or pagination, but the barrier for read-only tools is lower, and the description carries its weight.

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 description is compact: one sentence defines the output nature, resolution, and platform dimension, and a second sentence gives concrete use cases. Every sentence earns its place without padding.

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 simple read-only tool with three parameters, this is mostly complete: it defines data nature, resolution, scope, and suggested applications. Because there is no output schema, the description could be more explicit about response shape or ordering, but the core selection and invocation context are still solid.

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?

All parameters are documented in the input schema with meaningful descriptions, so baseline is 3. The description adds little over the schema. No additional parameter clarification is required, so a middle score 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 uses a specific verb and resource: returns a raw follower-count time series for a contestant. It also adds dimensional details (per platform, ~30-minute resolution) that make the tool's role clear and distinguish it from siblings like get_follow_events or get_engagement. The intended data shape is unambiguous.

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 explicitly says when to use this tool — for charts, growth analysis, and before/after comparisons around episodes. It does not mention alternatives or state when not to use it, but the semantic focus on raw time-series data makes the use case sufficiently clear.

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?

The readOnlyHint annotation already signals safety. The description adds useful behavioral detail: events are confirmed, ordering is newest-first, and there is a 200-item cap. It does not discuss pagination or response format, but it meaningfully extends beyond the 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?

Two sentences with no filler. The first sentence conveys purpose, scope, ordering, and limit; the second states filtering options. Every clause contributes useful information, and the key identifying detail 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?

As a read-only, two-parameter list tool, the description is nearly sufficient: it covers what events are returned, their ordering, the limit, and available filters. The only notable omission is explicit routing guidance against sibling tools like get_follower_history, but this is not critical given the strong purpose clarity.

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 both show and contestant already documented using examples and lookup guidance. The description only says 'filter by season and/or contestant,' which adds little beyond what the schema already provides.

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 clear verb and resource: confirmed follow/unfollow events among castmates, newest first, capped at 200. It differentiates this from sibling tools like get_follower_history or get_follow_graph by making clear this is a discrete event list rather than historical counts or relationship structure.

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 gives a clear usage context: use this tool to fetch confirmed follow/unfollow events and optionally narrow by season and/or contestant. It does not explicitly name alternatives or exclusion cases, but the focus on events makes the intended use easy to infer relative to the sibling tools.

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?

The readOnlyHint annotation already covers safety, and the description adds useful context: it is a point-in-time Instagram edge snapshot scoped to castmates. However, it does not disclose output shape, possible absence of one side of the graph, or how the 'current' snapshot is maintained, so it stays at baseline rather than rising much.

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 core behavior is front-loaded in the first sentence, and the second sentence provides a useful pointer to an alternative tool. There is no redundant explanation of the parameters or repetition of the schema.

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 low-complexity, read-only tool with two well-documented parameters, the description is complete enough for an agent to select and call it correctly. It communicates what the result represents, the scope of the graph, and the key sibling to use for a different need.

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 have clear descriptions with ID/slug examples and discovery guidance. The description does not need to add parameter details for the agent to invoke the tool 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 and resource: it retrieves who a contestant currently follows and who follows them among their Instagram castmates. This clearly distinguishes it from get_follow_events, which is the historical/unfollow counterpart.

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 'currently' establishes that this is for the present snapshot of the follow graph, and it explicitly says 'For unfollows, use get_follow_events.' This gives the agent a clear routing decision between the two most confusable sibling tools.

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?

With readOnlyHint already covering non-mutating behavior, the description adds useful transparency about what the response contains (titles, network, status, air dates, trackingStart/trackingEnd, coverageNote, episode count). It does not mention edge-case behavior like invalid IDs or response shape, but for a simple read it is adequate.

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?

A single front-loaded sentence communicates the operation, scope, and explicit payload fields with no filler. It earns its place entirely.

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 read-only tool with no output schema, the description covers what will be returned and the schema covers the input. No critical information an agent needs to call 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% and the schema's 'show' parameter already includes a clear format, an example, and a discovery hint. The tool description adds no additional parameter meaning, so the baseline of 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 uses a specific verb ('Get'), names the exact resource ('one season's details'), and enumerates the distinguishing fields (network, air dates, reunion date, tracking window, episode count), which separates it clearly from sibling tools like get_cast or get_follower_history.

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?

No guidance is given about when to choose this tool over alternatives or when not to use it. The only related hint, 'Use list_shows to discover,' appears in the parameter schema and addresses ID discovery, not tool selection.

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?

The readOnlyHint annotation already establishes that this is a safe read operation, so the description does not need to repeat that. The description adds some output context ('follower surges and drops', 'episode context'), but it does not disclose ordering, recency, pagination, or any computational caveats. There is no contradiction with 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?

One tightly worded sentence that front-loads the core behavior ('Detected follower surges and drops') and then adds the clarifying product context ('headlines behind PopOff trend cards'). No redundant or filler content.

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 simple optional-parameter read-only tool and no output schema, the description gives enough context about what is returned: detected trend events, episode context, and the pop-under behind the cards. It could mention return format or ordering, but the combination of description and schema is sufficient for an agent to select and call the tool.

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 each parameter is already documented with meaningful descriptions. The tool description adds no extra meaning about filters, status behavior, or contestant/show slugs. Baseline 3 is appropriate because the schema carries the parameter semantics.

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 clearly identifies the resource as trend events and adds useful specificity: follower surges and drops with episode context, tied to PopOff trend cards. It is reasonably distinct from siblings like get_follow_events or get_follower_history, though it does not explicitly name a sibling or restate an imperative verb like 'get'.

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 implies a usage context — PopOff trend card headlines — but never says when to prefer this tool over get_follow_events or get_follower_history. There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer boundaries from the tool name and the phrase 'trend events'.

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 only signal readOnlyHint=true. The description adds valuable behavioral context beyond that: it is not billed as a call, and it details what information will be returned. This gives the agent an accurate cost-aware picture before invoking the tool.

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 description is two sentences with no wasted words. The most important scoping detail ('this billing period') and cost behavior ('not billed as a call') are placed upfront, and the rest adds concrete enumerations of return contents.

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 zero-parameter, read-only tool, the description fully captures what the agent needs: what data the tool covers, what results are returned, and an important cost-related behavior. There is no meaningful missing context that would block correct invocation.

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 has zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. Under the baseline for a zero-parameter tool, this 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 clearly states the verb (get) and resource (usage/quota for the billing period), and also specifies scope across both MCP server and REST API. It includes concrete content details like units used, included quota, overage, and breakdowns, making it distinct from sibling data tools.

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 clearly implies when to use it: whenever an agent needs billing-period usage, quota, or overage information. It does not explicitly name alternatives or exclusions, but with zero parameters and a unique purpose among siblings, this is not a significant gap.

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?

The readOnlyHint annotation already covers the safety profile, so the description doesn't need to repeat that. The description adds output-content detail but reveals no additional behavioral traits such as pagination, ordering, or response shape. This is adequate but not rich.

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?

A single sentence states the action, resource, and output fields, including the enum-like episode types. Every element earns its place and the most important information 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?

For a simple read-only list operation with one well-documented parameter, the description is complete: it states what is listed, what fields are returned, and the parameter schema explains how to identify the season. No output schema exists, but the description sufficiently covers the return values.

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 input schema fully documents the single parameter with a clear description, examples, and a discovery pointer to list_shows. The tool description itself adds no parameter meaning beyond what the schema already provides, so the baseline of 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 uses a specific verb ('List'), names the resource ('a season's episodes'), and enumerates the output fields (air dates, air timestamps, episode types). This clearly distinguishes it from sibling tools like list_shows and get_show.

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 intended use is clear from the description: list episodes for a known season. The parameter description adds a useful prerequisite and discovery hint ('Use list_shows to discover'), but the main description does not explicitly state when not to use this tool or compare it against alternatives.

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?

The annotation readOnlyHint=true already covers safety; the description adds meaning by explaining that status is computed and by detailing the returned fields (tracking window, coverageNote, etc.), giving the agent a clear picture of what the call returns without side effects.

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 description is two sentences, front-loads the purpose, and packs useful detail (fields returned, franchise guidance) without redundancy. Every sentence earns its place.

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 read-only listing tool with one optional parameter, the description covers the return payload, the discovery use case, and the franchise nuance. No output schema is needed since the field list is explicitly enumerated.

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 schema fully documents the single optional parameter 'status' with an enum and a description ('Only return seasons with this status'), and the tool description adds no extra semantics beyond that. 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 states a specific action (list) and resource (tracked seasons) and enumerates the computed fields returned, distinguishing it from siblings like list_episodes (which lists episodes) and get_show (which retrieves a single show). The phrase 'Start here to discover what data exists' establishes its role as a discovery tool.

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 explicitly directs the agent to start here for data discovery and clarifies how to handle multi-season franchises (use the most recent season for unqualified questions). However, it does not explicitly name alternative tools or state when not to use it, leaving some inference to the agent.

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