apiwatch

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's real contribution is the scoping semantics: a record scoped to some code is returned with that scope spelled out and never as an unconditional hit. That is non-obvious behavioral detail an agent could not get from annotations. It doesn't discuss truncation or partial-failure behavior when some identifiers miss, which keeps it from 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 sentences, front-loaded with the verb and the identifier categories, then the answer shape, then the scoping caveat. The parenthetical about repos depending on an SDK major version is long but it is the clearest illustration of the scoping rule, so it earns its space.

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 an output schema present the description needn't explain return values, and annotations cover the safety profile, so what remains — what inputs are valid, what comes back per identifier, and how scoped hits differ — is all addressed. A missed-identifier or empty-result case is the only notable omission.

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 well constrained, so the baseline would be 3; the description adds value by enumerating what counts as an identifier (model ids, endpoints, MCP tool names, SDK methods, field names) and restating the 100-item cap. That said, the description provides no batching or normalization guidance for inputs beyond the example list.

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 ('Look up') plus a concrete resource set — model ids, API endpoints, MCP tool names, SDK methods, field names — and the phrase 'many identifiers at once' distinguishes it from the single-lookup sibling check_model. It stops short of naming the sibling explicitly, so the differentiation is implied 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?

'before shipping code' gives a genuine usage context, and 'many at once' hints at when to prefer this over check_model. There is no explicit when-not guidance and no sibling named as an alternative, so the routing decision is left partly 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?

Annotations already cover readOnly/idempotent/openWorld, and the description still adds materially: the negative-result caveat ("No record means apiwatch has no record for it, not that it is safe") and the scoping caveat that some records apply only in certain repos or files. These are exactly the interpretive details an agent would otherwise get wrong.

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 sentences, front-loaded with purpose and then usage timing, with no filler. The return-value sentence is a dense enumeration that partly duplicates the output schema, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool the description is complete: purpose, timing, result shape, negative-result interpretation, and scope caveats are all present, and annotations cover the safety profile. An agent has everything needed to call it and interpret results.

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 already says "The model id as it appears in code", so the schema does the heavy lifting. The description adds concrete format examples ("gpt-4o-2024-05-13", "claude-sonnet-4-5") that help the agent format the value correctly, which is a modest but real gain over baseline.

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 precise verb and resource ("look up one AI model id") within a named corpus ("apiwatch's reviewed feed of vendor changes") and gives two concrete id examples. The single-record lookup scope clearly separates it from siblings like search_changes or list_upcoming.

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?

"before you use it in code" gives an explicit usage moment, which is more than most descriptions offer. It stops short of naming alternatives (e.g. check_identifiers for non-model ids) or stating when not to use it, so it falls short of a 5.

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

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 profile is covered. The description adds that the record is returned complete and 'as published' (no summarization), which is useful, but it says nothing about behavior on an invalid/unknown id or lookup failure.

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 action is front-loaded in the first clause, and the second sentence gives the id source. The long comma-list of record contents is a bit dense and overlaps the output schema, keeping it short of a 5.

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 one fully described required parameter, an output schema, and annotations covering the safety profile, the description is sufficient to invoke correctly. Only missing element is failure/not-found behavior for a bad id.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema supplies a concrete example id, so the parameter is fully documented. The description adds only the provenance hint that the id comes from another tool's result, which is marginal but not zero value; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('one apiwatch record') plus the scope 'in full, as published', and enumerates the payload (changes, remediation, search strings, uncovered ids, applicability, vendor source, review date). That distinguishes it clearly from list_upcoming, search_changes and mcp_server_changes, which are plural or change-oriented.

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?

'Use an id from another tool's result' implies the intended workflow (search/list first, then fetch details) but never names which sibling produces such ids or states when not to use this tool. Usage is inferable rather than 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 declare read-only, idempotent, non-destructive, closed-world behavior. The description adds useful behavioral details beyond that: results are future-only, sorted soonest first, capped at 50 records, and optionally bounded by days or vendor. It does not explain what happens if more than 50 records match.

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, ordering, categories, purpose, and optional filters are packed into a tight description with no filler. The most important information, what is listed and how it is ordered, 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?

Given the rich annotations, complete parameter schema, and existing output schema, this description provides enough context to call the tool correctly. It covers scope, ordering, categories, defaults, and the record cap.

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%, so both parameters are already documented in the schema. The description restates the default and maximum for days and gives vendor examples, but adds little semantic detail beyond the structured 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 states a specific verb and resource: listing dated changes from today forward, soonest first, across named change categories. The temporal scope and ordering clearly distinguish it from a general search_changes tool without needing to name siblings 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?

It explicitly says to use the tool to plan migrations, giving a clear usage context. It does not name when to use alternatives such as search_changes or get_record, so it falls short of full when/when-not routing.

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, but the description adds real behavioral context beyond them: the 6-hour polling cadence, that only tools/list is invoked with no login and no tool calls, and the exact status vocabulary (answering, needs a login, not reachable). That is precisely the operational context an agent needs to interpret staleness and status values.

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, front-loaded with the scope, then the return fields, then the routing hint and the negative constraint. The parentheticals are dense but 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?

An output schema exists, yet the description still summarizes the returned fields and status values, and it closes the one ambiguity a listing tool creates (that it does not return tool descriptions). Nothing needed 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly avoids inventing filter options that the empty schema does not support.

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 ('List the public MCP servers whose tools apiwatch checks every 6 hours') and enumerates exactly what is returned (status, tool count, last check, last observed change). It also distinguishes itself from the sibling mcp_server_changes by framing itself as the index of what that tool can answer about.

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?

'Use it to see which servers mcp_server_changes can answer about' explicitly names the alternative and the condition that selects it. The parenthetical 'tools/list only, no login, no tool calls' plus 'Returns no tool descriptions' pre-empts the most likely misuse (expecting tool-level detail).

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; the description adds real value on top: return shape (one-line answer plus confirmed changes, newest first), a default/limit window (90, max 365), and an important honesty caveat that absence of changes is not a safety guarantee. It also discloses a data boundary ('never includes tool description text'), though it says nothing about rate limits or auth.

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?

Information-dense with no wasted clauses, but the rhetorical opener ('ask whether apiwatch saw them change') delays the actual action statement. The operational content — inputs, window, return shape, caveat — is all present and mostly 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 two-parameter read tool with full schema coverage, complete annotations and an output schema, the description covers everything an agent needs: what it reports, how to identify the server, the time window, ordering, and the interpretive caveat about 'no changes'.

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 description merely restates what the schema already documents: accepted server formats (slug, URL, registry name) and the 90/365 day window. No added syntax, precedence rules, or failure behavior for unresolvable server identifiers.

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 concrete resource and scope: tool-level changes (removed, renamed, new required params, rewritten descriptions, changed safety hints) for one named MCP server. That is specific enough for an agent to distinguish it from a broad change search, though it never names a sibling like search_changes or list_watched_mcp_servers to sharpen the boundary.

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 a clear trigger — 'Before you rely on a public MCP server's tools' — and a prerequisite hint via 'a watched server's slug'. It stops short of explicit exclusions or naming which sibling to use for unwatched servers or cross-server change hunting.

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 and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: matching is case-insensitive, results are ordered newest key date first, and the result window defaults to 20 with a hard cap of 50.

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 the matching semantics front-loaded and no filler. The only wasted effort is restating the 20 default and 50 maximum that the limit schema already enforces.

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?

An output schema exists so return shape need not be explained, and the description covers matching rules, ordering and result limits. What is missing is minor: no mention of what happens on zero matches or whether cursor-based paging beyond limit is possible.

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 query parameter carries no schema description, and the description compensates by explaining that it is matched case-insensitively against summary, vendor and signatures. Limit and vendor are already documented in the schema, and the description only repeats the 20/50 bounds rather than adding to them.

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 (search) plus resource (apiwatch's feed of reviewed vendor changes) and exactly what text is matched against: summary, vendor and signatures. It also distinguishes itself from id-based lookup by saying it is for when you know a name 'but not the exact id'.

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 clear triggering condition ('when you know a product or feature name but not the exact id'), which implicitly separates it from get_record. It does not name get_record as the alternative outright, so the exclusion is inferable rather than explicit.

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