aggregate_steam_review_corpus

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 aggregation is server-side and that a metadata-enabled corpus is required (implying failure otherwise), but it omits the read-only nature, response shape, and any limits or rate constraints. Adequate but incomplete for a 12-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?

Three sentences: purpose first, then capabilities, then precondition. Well front-loaded and largely waste-free, though the capability enumeration is a fairly long run-on list that could be tightened.

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 12-parameter tool with no annotations and no output schema, the definition should explain the return shape, but it never does – it only names aggregation types. Combined with the missing alternatives guidance, the picture is serviceable but not 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 description coverage is 100%, so the schema documents all 12 parameters (date filters, group_by grain, voted_up sentiment, language list, playtime thresholds, text match). The description's capability list maps loosely onto these but adds no syntax, units, or defaults beyond what the schema already states.

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 ('Aggregates a stored Steam review corpus server-side') and enumerates the aggregation outputs it produces. It implicitly separates itself from query_steam_review_corpus by framing the tool as summarization rather than retrieval, but it never names the sibling explicitly to fully disambiguate.

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 states a prerequisite ('Requires a corpus created with review metadata enabled'), which is genuine usage guidance, but it never says when to choose this over query_steam_review_corpus or the corpus-status tools. Usage is implied by the enumeration of capabilities rather than prescribed.

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