Measured data: Claude Code and the coding-agent market

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

With no annotations, the description carries the disclosure burden. 'Measured anatomy' implies a read-only analysis, and the sample-size/cap details add useful context, but there is no explicit statement of side effects, output representation, freshness, or other runtime behavior.

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 compact sentence front-loads the artifact and uses a colon to enumerate the exact metrics. Every phrase earns its place; there is no filler or boilerplate.

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 no-parameter tool, the description supplies enough context to invoke it: what the analysis covers, the sample size, and the key comparison condition. It does not describe the response shape, but with no output schema this is a minor gap.

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 an empty input schema, so there is nothing the description needs to explain. The baseline of 4 applies because no parameter guidance is required.

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 identifies a concrete artifact—a measured anatomy of 160 Claude Code sessions—and names the metrics covered: cache-read share, oversized tool-output share, and the replay effect. It is specific enough to distinguish this from sibling tools, though it lacks an explicit verb like 'returns' or 'shows' to state the operation.

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 guidance on when to choose this tool over its siblings, even though tools like show_hn_claude_code_stats and issue_gap_map are plausibly related. The content implies a use case around Claude Code cost analysis, but the description never states when it should or should not be used.

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 provided, the description carries the full burden of behavioral disclosure. It states the output format (JSON), which is useful, but does not disclose whether the operation is read-only, side-effect-free, or requires authentication. For a retrieval tool, this is a minor gap, but the description adds only minimal behavioral context.

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, well-structured sentence that front-loads the action and resource, followed by the necessary enumeration. There is no wasted wording, and the list is essential for correct usage.

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 single-parameter tool with no output schema, the description covers the key information: what it returns (JSON) and the valid inputs. It does not mention error handling or authentication, but these are minor for a basic get operation. The description is largely sufficient.

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 provides a single 'name' parameter with no description, enum, or format (0% coverage). The description fully compensates by listing all eight valid dataset names, which gives the agent precise guidance on what values are acceptable. This goes far beyond 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 states the action ('Return') and the resource ('one dataset as JSON'), and explicitly enumerates the valid dataset names. This distinguishes it from siblings like claude_code_cost_anatomy and github_trending, which are purpose-specific 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 list of valid names provides clear context on which datasets can be retrieved with this tool, implicitly indicating that for these specific datasets, get_dataset is the correct tool. However, it does not explicitly state when to prefer a sibling tool or mention exclusions, so it falls short of an explicit when/when-not 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?

With no annotations, the description carries the behavioral burden. It usefully discloses that data is scraped daily, archived, and lacks official history, which explains staleness and date availability. However, it doesn't mention side effects (likely none) or failure behavior when a requested snapshot is missing.

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 compact sentences convey the full scope and key caveat without redundancy. The punctuation is slightly dense, but the content is front-loaded and every phrase 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 an unannotated tool with no output schema, the description covers the main selection logic but leaves the agent guessing about default behavior when no parameters are provided, limit semantics, and the shape of the returned data. These gaps are moderate, not critical.

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 only 25%, but the description compensates by explaining the since options ('today's list, this week, this month') and linking date to 'past day's snapshot,' plus language to daily lists. It omits limit, though the schema's min/max partially covers that parameter.

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?

Identifies a specific resource (GitHub Trending) and enumerates all query modes: daily/weekly/monthly lists, language-specific daily lists, and archived date snapshots. The parenthetical about no official API/history further differentiates it and sets expectations.

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 maps use cases to parameter choices (today/week/month to since, language to language, past day to date), making when-to-use apparent. It doesn't name alternatives, but the sibling tools are unrelated and this tool's niche is unmistakable.

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 burden. It discloses that the tool returns 'top open issues by thumbs-up' and that it is limited to the three repos, but it doesn't disclose whether the data is live or cached, how 'top' is defined (e.g., exact sort order, tie-breaking), or whether the limit parameter affects the result. It adds some behavioral context beyond the schema but not rich detail.

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, compact sentence that front-loads the core purpose and lists the exact repos. Every word earns its place; no filler or 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 simple two-parameter tool with no output schema, the description is mostly adequate. However, it doesn't explain what the output looks like (e.g., list of issues with titles, URLs, counts) or how the limit parameter behaves. Given the tool's simplicity, a 3 is appropriate: it's usable but leaves some gaps.

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. The description names the repo parameter implicitly by listing the three repos, and the limit parameter is not mentioned at all. The schema already provides enums and min/max, so the description adds little beyond the repo list. A 3 is fair because the description partially compensates but doesn't explain limit semantics or result shape.

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 ('Top open issues by thumbs-up') and a specific resource (three named repos), and it conveys the core value: what users ask for loudest that is still open. It clearly distinguishes itself from sibling tools like github_trending or get_dataset by focusing on issue-gap analysis for three specific AI coding repos.

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 when to use it: when you want top open issues by thumbs-up for one of the three repos. It doesn't explicitly state when not to use it or name alternatives, but the context signals and sibling list make the use case clear. A 4 is appropriate because the context is clear but exclusions are not stated.

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 burden of explaining behavior. It clearly states what the tool lists and mentions pull dates, which is useful, but it does not disclose output format, pagination, authentication needs, or whether this is a read-only operation. The verb 'List' implies non-mutating behavior, but no explicit safety or side-effect information is given.

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 sentence that front-loads the core action and resource, then efficiently enumerates the specific datasets and includes the pull-date detail. Every element adds useful information; there is no filler or redundancy.

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 listing tool, the description provides enough context to understand what will be returned at a high level (dataset names and pull dates). It could be slightly more complete by stating the output format or explicitly noting that it returns metadata rather than dataset contents, but given the tool's simplicity this is a minor gap.

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 nothing for the description to add about parameter meaning. The baseline of 4 applies because the description is not required to compensate for any undocumented parameters.

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') with a clear resource ('measured datasets') and enumerates the specific datasets included, plus the key detail of pull dates. This distinguishes it from sibling tools like get_dataset (which retrieves a single dataset) and other domain-specific 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 implies this is the discovery/overview tool among siblings, but it never explicitly says when to use it over get_dataset or other dataset-specific tools. There is no direct guidance on alternatives, exclusions, or prerequisites.

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 itself must convey behavioral characteristics. It does so by specifying 'full-crawl census of the official MCP registry,' which indicates a read-only, aggregate analysis over the entire registry rather than a sample or a mutation. It also enumerates the exact metrics, making the tool's behavior predictable. It still does not state refresh cadence, staleness, or whether any network fetch occurs, but for a zero-parameter reporting tool this is reasonably transparent.

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, compact sentence that front-loads the core scope ('full-crawl census of the official MCP registry') and then enumerates the key metric groups. There is no filler or repetition. It could be slightly improved by adding an explicit verb at the start, but the current length is well-suited to a zero-parameter tool.

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 parameterless reporting tool with no output schema, the description is nearly sufficient on its own. It tells the agent what registry is coveredainer and which aggregate metrics are availablekusuma. It does not describe the output format or data types, but with no output schema available the missing return details are a moderate gap rather than a fatal one, especially since the metric names are descriptive.

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 no parameters, so the input schema is trivially complete and the description does not need to explain parameter behavior. The description adds value by explaining what the 'census' returns, which compensates for the absence of schema detail. A score of 4 is appropriate because there is nothing about parameters the agent needs to infer.

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 identifies a specific resource (the official MCP registry) and the exact metrics returned (unique servers, new servers per day, remote share, share with no auth). It lacks an explicit action verb like 'returns' or 'computes,' but 'full-crawl census' effectively conveys the operation. The tool is also clearly distinguishable from all listed 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 implies when to use the tool: whenever an agent needs registry-wide MCP server statistics such as growth and auth coverage. However, it does not explicitly state candidate scenarios, prerequisites, or when a sibling tool would be a better choice. With no parameters and no alternatives mentioned, usage guidance remains mostly implicit.

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 present, so the description carries the full burden of behavioral disclosure. It transparently states the filtering rule (title contains 'Claude Code') and the time window (last 90 days), but it does not explicitly affirm that the tool is read-only or side-effect-free. Given the tool's name ('show') and the nature of the query, this is a minor omission rather than a serious gap, but it still prevents a higher score.

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, well-structured sentence that front-loads the primary subject and packs all essential details (scope, time range, and output metrics) without any filler. Every word contributes to the agent's understanding.

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 tool with no output schema, the description lists every output dimension the agent will receive (count, median, p75, p90, share reaching 50 points, top posts) and the exact input scope. Nothing essential for invoking the tool and interpreting its results 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 has zero parameters, and the input schema confirms this (100% coverage vacuously). With no parameters to document, the baseline score of 4 applies; the description adds no parameter semantics because none are needed.

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 resource (Show HN launches with 'Claude Code' in the title over the last 90 days) and enumerates the exact output metrics (count, median, p75, p90, share reaching 50 points, top posts). This clearly distinguishes it from sibling tools like github_trending or issue_gap_map, which target different datasets and questions.

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 does not explicitly name when to use it over alternatives, but the precise scoping ('every Show HN launch with 'Claude Code' in the title over the last 90 days') makes the intended context unmistakable. An agent can easily infer this tool is for Show HN-specific Claude Code stats, and no sibling offers a similar focused view.

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