Platform Changes

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

No annotations are provided, so the description carries the full burden. It usefully discloses that this returns the complete stored record including the full summary (vs truncated output elsewhere), but says nothing about permissions, behavior for unknown ids, or what the record contains beyond the summary.

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, front-loaded with the object of the operation and no filler. It is terse to the point of being slightly clipped ('including the full summary' hints at a distinction from siblings without stating it), 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 simple read-by-id tool with one parameter and no output schema, the description covers the essentials but leaves the return shape and failure modes unstated. Adequate minimum for the complexity, not more.

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% and the single parameter has no description, so the schema only tells the agent it is a string. The description partially compensates by specifying the id must be one previously returned by the other tools, which is the one semantic detail that matters here.

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

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

Names a specific verb+resource: fetch the full stored record for one change id, and notes it includes the 'full summary'. That distinguishes it from list_sources/recent_changes/search_changes, which evidently return abbreviated records, though no sibling is named 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?

The parenthetical '(as returned by the other tools)' tells the agent where a valid change_id comes from, which is real usage context. There is no explicit statement of when to prefer this over search_changes or recent_changes, and no error/prerequisite guidance.

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 implies a read-only listing and mentions the returned fields (last poll time, item counts), but says nothing about permissions, freshness/refresh behavior, or whether counts are cumulative or windowed. Adequate but thin for a zero-annotation 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 front-loaded sentence with no filler; the verb, resource, and payload are all stated immediately and every clause 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?

The tool is simple (zero params) and an output schema exists, so return-value details are already covered structurally. The only gap is the absence of when-to-use guidance relative to the sibling change tools.

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 no parameters at all, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter detail is needed or expected.

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') and a specific resource ('the platforms and official sources this feed monitors'), which is clearly distinct from the change-oriented siblings (get_change, recent_changes, search_changes, weekly_digest). An agent can tell this is the source-inventory tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the phrase 'this feed monitors' hints that this is a discovery/overview call, but there is no explicit statement of when to call it versus the change-listing siblings, nor any prerequisites. Minimum viable.

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 mostly does so: it discloses that summaries are truncated, that importance is 'AI-rated or heuristic (see importance_basis)', and that by='updated' surfaces older posts edited recently. It omits any note on rate limits or auth, but the behavioral picture is well above the norm for an unannotated 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?

Front-loads the one-line purpose, then one line per parameter, then a routing pointer to get_change. Dense and largely waste-free, though the parameter dump reads as a flat list rather than being prioritized by importance.

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 six-param list tool with an output schema present, the description covers filtering, ordering, bounds, and truncation behavior sufficiently. Nothing critical is missing for correct invocation, though the lack of sibling differentiation keeps it short of fully complete.

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 do all the work, and it does: every one of the six parameters is defined with meaning, bounds (days max 90, limit max 50), and enumerated values (platform list, tag list, min_importance levels). It even supplies enum context the schema lacks entirely.

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 ('Recent platform changes, newest first') with a clear ordering guarantee. It does not distinguish itself from the sibling search_changes, which retrieves a similar resource, so an agent still has to infer the boundary between the two.

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 routes the agent to get_change for full text and explains what min_importance is for ('drop routine release noise'), which is genuine conditional guidance. However, it never says when to prefer this tool over search_changes or weekly_digest, leaving the main routing decision unaddressed.

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 supply useful traits: case-insensitivity, the searched fields, newest-first ordering, and a hard cap of 50 on limit. It still omits pagination/offset behavior, whether the search spans all sources, and what an empty result set looks like — meaningful gaps for an unannotated 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?

Two short sentences with zero filler; the search scope and ordering come first, the constraint second. Every clause 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?

An output schema exists, so return-value documentation is not required, and the description covers scope, ordering, and the limit cap. Minor gaps remain (no-match behavior, whether the cap is a validation error or a silent clamp, no cross-source scope statement), but nothing essential for correct invocation 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 description coverage is 0%, so the description must compensate. It adds real value on 'limit' by stating the maximum of 50 (the schema only shows a default of 20), and clarifies that 'query' matches titles and summaries case-insensitively. It does not explain the default value or what happens if limit is omitted.

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 ('text search over change titles and summaries') plus the search field scope and sort order, which is more than the name alone conveys. It implies a filtered-search role distinct from recent_changes/get_change, but never names those siblings, so the differentiation is left to 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?

Usage is only implied: an agent can infer this is the tool for keyword lookup rather than fetching a known change. There is no explicit when-to-use statement, no when-not-to-use (e.g., prefer recent_changes for browsing), and no mention of 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?

With no annotations, the description carries the full burden and discloses meaningful traits: the ranking logic (importance via AI-rating with heuristic fallback, then recency), hard caps (days max 30, per_platform max 10), and a caveat to read source_url before acting. It omits error/empty-result behavior and permission needs, keeping it just short of top marks.

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?

Extremely compact and front-loaded: purpose first, then parameters, then ranking and a caveat. Every sentence carries information with no 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 tool with no output schema, no annotations, and an undocumented schema, the description covers inputs, ranking, limits, and a safety caveat well. It stops short of describing the return shape beyond 'short ranked overview ... grouped by platform', so an agent gets limited signal on response structure.

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% and the schema has no descriptions or enums, yet the description documents all three parameters: the exact valid platform values, the days look-back window with its max, and per_platform with its max. This adds substantial meaning the structured fields entirely lack.

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+resource: a short ranked overview of the most important recent changes grouped by platform. It does not explicitly differentiate itself from siblings like recent_changes or search_changes, so an agent must infer the distinction from 'Best first call'.

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?

'Best first call' is a clear, actionable directive that tells the agent when this tool should be used relative to others. However, it names no alternative and gives no exclusion conditions (e.g., when to fall back to recent_changes or search_changes).

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