AI Deprecations

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

With no annotations, the description carries the full burden and does well: it discloses the history boundary ('History starts at tracking_since'), the warning triggered by an earlier since, and the important caveat that count 0 plus a warning does not mean nothing changed. It does not cover pagination, rate limits, or what the response body looks like beyond checked_at, so it is not complete.

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 doing distinct work: what changes are tracked, how to poll, and the history/count-0 pitfall. Front-loaded with the purpose and zero 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 two-parameter read tool with no output schema and no annotations, the description covers purpose, polling protocol, and the main correctness trap. The only real gap is the unmentioned `provider` filter and a lack of any return-shape hint beyond checked_at.

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 50%: `since` is documented in the schema and the description enriches it meaningfully (clamped by tracking_since, earlier values yield a warning). The `provider` parameter is undocumented in both schema and description, so the description only partially compensates for the coverage gap. 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?

A specific verb ('List') plus a precisely scoped resource ('tracked AI model records whose status, deprecation/shutdown date, replacement or source changed'), with an explicit time qualifier. That enumeration makes it clearly distinct in kind from get_provider or get_shutdown_date, though no sibling is named. It falls short of 5 only because the differentiation must be inferred rather than stated.

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 a concrete operating pattern: 'Poll this to stay current: on later calls pass the previous response's checked_at.' That is real when-to-use guidance tied to a follow-up call. It stops short of explicit exclusions (e.g., when to prefer list_upcoming or search_models instead), so 4 rather than 5.

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 no annotations, the description must carry the full behavioral burden. It does disclose that manual source reviews are 'empty until one is recorded' and that a replacement_kind rule is included, which are non-obvious behaviors. It does not state that the operation is read-only/side-effect free, what 'today' means (timezone/cutoff), or how large the response can get, so the safety and cost profile remain unclear.

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 scope statement is front-loaded and the enumerated categories are compact. The parenthetical explaining manual source reviews is useful rather than filler, though the single sprawling sentence mixes return-value categories with schema-adjacent notes.

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, so the description is the only place the return shape can be conveyed. It lists the categories but does not say whether they are counts, lists of rows, or nested per-provider objects, and it references a 'replacement_kind rule' without explaining it. Adequate for gist, not for predicting the payload.

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% with a single optional 'provider' key, so baseline is 3. The description's phrase 'Per-provider coverage' hints that provider scopes the result, but it never says whether omitting the parameter aggregates across all providers. That is the one semantic the schema cannot express, and it is left unstated.

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 resource precisely (per-provider coverage for today) and enumerates the categories returned: rows with a known shutdown date, rows with no vendor date, rows not verified today, and unreadable official pages. That is specific enough for an agent to know it is a coverage/reporting tool rather than a record lookup. It never explicitly contrasts itself with siblings such as get_provider or list_upcoming, so the sibling differentiation is only implicit.

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 statement of when to call this tool instead of get_provider, list_upcoming, or get_changes_since, and no prerequisites or exclusions. The name and content imply a 'how complete is the data' use case, but the agent must infer that. Clear gaps for a tool with six siblings.

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?

No annotations exist, so the description carries the full burden, yet it never states this is a read-only lookup, what happens for an unrecognized or untracked provider, or what 'tracked' means (whether untracked models are excluded). It also gives no hint on return shape or ordering.

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 with no filler; the provider examples are placed where they are needed. Slightly compressed to the point of under-specification, 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?

For a one-param read tool with no annotations and no output schema, the description covers purpose and valid values but omits behavioral essentials: read-only nature, error handling for unknown providers, and whether the valid provider list is closed.

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 0%, so the description must compensate; it does by enumerating plausible provider values (openai, anthropic, google-gemini, azure-openai, aws-bedrock, etc.), which is genuinely useful. However, it doesn't say whether this list is exhaustive, case-sensitive, or what form an invalid value should take.

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 resource precisely: all tracked models scoped to a single provider, which is distinct from search_models. It lacks an explicit verb like 'list' but the scope ('all tracked models for one provider') makes the operation 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?

No statement of when to use this tool versus search_models or the other siblings; an agent must infer that this is the enumeration path versus the search path. No prerequisites or exclusions are given.

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 no annotations present, the description must carry the full disclosure burden, and it discloses little. It does not say what happens for an unknown or unreleased model (empty result vs. error), how fresh the shutdown data is, or whether it is a pure read. The mention that the result includes a 'source' is the one real disclosure, but it is thin for a tool with zero annotation coverage.

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 that names the resource, the returned fields, and example inputs, with no wasted words. The most important information, what the tool returns, comes first.

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 read with no output schema and no annotations, the description does cover the return shape (date, replacement, source), which is valuable. It nonetheless omits the not-found behavior and the provider param semantics, leaving real gaps given that no structured field fills them.

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 50%: the provider param documented but the required model param is not. The description partly compensates by showing example model IDs (gpt-4o-2024-08-06, claude-sonnet-4-5), which conveys the expected format. It adds nothing about the provider param's accepted values or effect, so the gap is only half closed.

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 ('Get the official deprecation/shutdown date') and even names the returned fields (date, replacement, source), so the agent knows exactly what comes back. It gives concrete model-ID examples in two naming conventions. However, it never names a sibling tool such as list_upcoming or search_models, so differentiation is left to the agent's inference.

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 guidance on when to use this instead of list_upcoming or search_models. The phrase 'for an AI model ID' implies single-model lookup, and the alternative — using list_upcoming for a bulk view — is never stated, nor is there any guidance on what to do when a model is not found.

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 no annotations, the description carries the burden; it does add real behavior by disclosing the sort order (soonest first), which the schema cannot express. However, it says nothing about whether results are bounded/truncated, what a missing provider match does, or the record shape returned for a 2-param read 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?

A single sentence that front-loads the action, resource, scope and ordering with no filler. Nothing is padded.

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 tool with zero annotation coverage, no output schema and an entirely undocumented parameter schema, the one-line description is thin. An agent cannot tell how the provider filter behaves or whether the result set is capped before calling it.

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 0%, so the description must compensate and it largely fails: 'next N days' hints at the days parameter but omits its default (30) and the 1–3650 bounds, and the provider parameter is not mentioned at all, leaving its matching semantics (exact name? substring?) completely undefined.

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 ('List'), resource ('AI model shutdowns'), time scope ('next N days') and ordering ('soonest first'), so the agent knows exactly what it returns. It does not name any sibling for contrast, but the resource is distinct enough from search_models or get_shutdown_date that confusion is unlikely.

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 — an agent can infer this is the tool for upcoming shutdowns, but nothing states when to prefer it over get_changes_since or get_shutdown_date, nor any preconditions. No alternatives or exclusions 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?

With no annotations, the description carries the full burden. It usefully discloses that retired models are included in results, which is genuine behavioral context, but says nothing about matching/ranking, pagination, or return shape.

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 with no filler. Every element (verb, resource, scope, search field) 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 simple two-parameter search tool with no output schema, it covers the core purpose and query semantics. It falls short on limit/pagination behavior and does not indicate what a result record contains.

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 0%, so the description must compensate. It clarifies that the query parameter searches by name, but the limit parameter (default 20) and its pagination meaning are left entirely 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?

Specific verb (search) plus resource (tracked AI models) with a clear scope qualifier (including retired) and search field (by name). It clearly differs from siblings like list_upcoming and get_provider, though it doesn't name them 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 by the scope wording; there is no explicit statement of when to use this versus get_provider, list_upcoming, or get_changes_since. No when-not guidance or prerequisites are given.

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 no annotations, the description carries the full burden and does well: it discloses delivery mechanics (JSON POST on every change, daily checking), the double opt-in flow for email, and that webhooks get an unsubscribe token. It doesn't cover auth/prerequisite or what happens if both channels are supplied.

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 dense sentences, front-loaded with the purpose, then the channel options, then the filter and return value. No filler, every clause carries 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 3-optional-param tool with no output schema and no annotations, the description covers delivery behavior and the returned unsubscribe token well. It leaves a gap on whether at least one of email/webhook is required and how conflicting combinations are handled.

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 0%, so the description must compensate and largely does: webhook must be a public https URL, email triggers a double opt-in newsletter, and providers is an optional filter. The semantics of what 'providers' filters on (provider identifiers) remains somewhat implicit.

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+resource ('Subscribe to deprecation/shutdown change alerts') that an agent can distinguish from siblings like unsubscribe and list_upcoming. It doesn't explicitly name sibling tools, but the operation 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?

Explains the two subscription channels and their tradeoffs (public https webhook with JSON POST checked daily, vs email with double opt-in newsletter), which is real channel-selection guidance. It stops short of saying when to pick this over a polling sibling like get_changes_since.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the effect (stops webhook alerts) and the auth mechanism (token), but says nothing about reversibility, whether the subscription is deleted permanently, or what the response looks like. Meaningful gaps remain for a mutation tool with zero annotation coverage.

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 the verb front-loaded and no filler. The second sentence is slightly ambiguous as agent-facing guidance but earns its place by clarifying the email path and token origin.

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 one-param tool with no annotations and no output schema, the description covers purpose, token source, and an alternative path. However, it omits the outcome/reversibility of unsubscribing and any indication of the return value, leaving the agent to infer post-call 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 single token parameter has 0% schema description coverage, so the schema adds nothing. The description partially compensates by stating the token originates from subscribe_alerts, but gives no format, length, or validity details. Adds real but incomplete value over 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?

States a specific verb and resource: 'Stop webhook alerts.' It also implicitly pairs with the sibling subscribe_alerts by naming it as the token source, so an agent can map the inverse relationship. The secondary reference to email unsubscription broadens scope slightly, but the core action is clear.

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?

Provides an explicit prerequisite ('using the token from subscribe_alerts') and distinguishes the path for email subscribers ('unsubscribe from the link in any email'), which effectively tells the agent when this tool is NOT the right mechanism. Doesn't fully spell out when-not conditions, but the alternative path is named.

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