The MCP Census

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

The description discloses several behavioral traits beyond annotations: it is not a malware scan, PASS is not a sandbox, UNKNOWN is never upgraded to PASS, it costs credits, and keyless callers have rate limits. It also advises stripping env/headers before sending, which is critical for safe invocation. Annotations are minimal (readOnlyHint false, etc.), so the description carries the full transparency burden and does so thoroughly.

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 dense paragraph that front-loads the purpose and packs in essential details (verdicts, exit codes, costs, security). Every sentence adds value, though it is longer than average; it remains efficient given the tool's complexity.

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 complex tool with 5 parameters and no output schema, the description covers the core return format (verdicts, CENSUS-AUDIT/1 text, valid_until_epoch, exit_code) and includes security and cost constraints. It omits details on policy_id and format parameters, but the schema covers some and the description provides enough for a competent agent to call it correctly.

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 60%, with descriptions for config, strict, and previous_tools_digests. The description adds context about config formats (object/string/array, Codex config.toml) and the overall audit behavior, but it does not explain format or policy_id, which lack schema descriptions. It partially compensates but leaves gaps.

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 a specific action: auditing a whole MCP client config, listing the exact config file types and describing the resolution and verdict behavior. It distinguishes itself from siblings like census_lookup by emphasizing whole-config auditing, so an agent can tell it apart without ambiguity.

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 provides strong context on when to use it (whole-config audit, resolving entries) and implicitly contrasts with per-entry tools, but it does not explicitly name an alternative or state when not to use it. The cost and rate-limit details further clarify appropriate usage.

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?

The description adds behavioral details beyond annotations: it is unmetered in v1, supports cursor pagination (pass next_cursor as since), and ensures no 'still fine' events. However, it does not describe the response structure or potential error cases, though the readOnly and idempotent hints are consistent.

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, information-dense paragraph that covers purpose, event types, pagination, filtering, and usage notes. It is concise without unnecessary fluff, though the phrase 'Not a malware scan' is an odd addition that adds little value.

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 five parameters and absence of an output schema, the description provides sufficient context for invocation: it explains pagination, filtering, and polling. It lacks an explicit description of the response format, but the nature of a change feed makes it reasonably inferable.

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?

All parameters have descriptive schema entries: limit has min/max/default, since is clearly explained, events/server_names/namespace_domain list their purposes. The tool description supplements the events parameter by listing the allowed event names, enhancing clarity.

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 tool's purpose as a change feed that reports transitions across servers, enumerating specific event types like server_new and health_change. It distinguishes itself from sibling tools by focusing on changes and includes the 'CENSUS-CHANGES/1' identifier.

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 provides specific usage guidance: cursor-paginated with next_cursor, filtering options via events, server_names, and namespace_domain, and a polling recommendation of hourly. It also clarifies that only real transitions are returned, but does not explicitly compare with siblings like census_recent.

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 disclosure burden. It does add useful behavioral context: the data is live, the endpoint is public and unmetered, and it explicitly says the tool never invents completeness percentages or a brand_audit punch list. This goes beyond a simple action statement, though it stops short of describing error behavior or response format details.

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, adds an endpoint alias, and includes a meaningful negative constraint. Every clause adds value and there is no redundant or filler wording.

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 public report tool with no output schema, the description provides a strong overview of the returned content and explicitly excludes certain false outputs. It lacks some detail like output formatting or error cases, but given the low complexity and zero parameters, it is complete enough for an agent to select and invoke the tool confidently.

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 schema is empty, so there is no parameter information to clarify. Per the baseline for parameterless tools, a score of 4 is appropriate; the description does not need to compensate for 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 clearly identifies the tool as a public transparency report and specifies exactly what it returns: live D1 census/identity/remote/protocol/adoption/pipeline counts plus method notes. It also references the equivalent HTTP endpoint (GET /v1/coverage), which removes ambiguity and helps distinguish it from the other census_* 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 the tool is appropriate—public transparency reporting, unmetered access—but it does not explicitly state conditions or name alternatives among the sibling tools. An agent can infer this is the go-to for coverage counts, but there is no direct when-to-use vs when-not-to-use 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 disclosure burden and uses it well: it states the operation is unmetered and clarifies a potentially surprising keyless fallback (anonymous unique-per-day remaining, not a wallet). It does not describe the exact response shape, but the key behavioral nuances are surfaced.

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 tightly packed sentences with the main purpose front-loaded and the important edge case in the second sentence. No filler or redundant restatement of the tool name.

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 read-style tool with no output schema, the description explains the core concept, the wallet timing, and the keyless exception, covering the main sources of confusion. It stops short of stating the exact return representation/type, so it is not 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?

There are no parameters and the schema coverage is trivially complete, so there is nothing for the description to add to parameter meanings. The no-parameter baseline of 4 applies, and the API-key/keyless context is useful environmental information.

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 ('Show'), a specific resource ('remaining Census credits for this API key'), and distinguishes keyed wallet results from anonymous per-day remaining. Clear and distinct from all census_* 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?

No sibling directly overlaps with credit checking, so no exclusionary routing is necessary. The keyed-vs-keyless distinction gives clear contextual guidance for what to expect, though it does not spell out when to prefer this tool over 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 provided, the description carries the behavioral burden and does add value: it discloses the output shape, the maximum number of lookalikes, the guarantee that it does not invent lookalikes, and a cost of 1. It does not explain what happens when there is no contested identity or failure behavior, but the provided details are meaningful.

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 with no filler. It front-loads the core purpose, then adds behavior and cost. Every sentence contributes useful 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 single-parameter tool with no output schema and no annotations, the description gives a useful picture of the return contents, the anti-hallucination guarantee, and the cost. It could be stronger by explaining 'contested identity' more explicitly or describing empty/no-contest cases, but it covers the essential invocation context.

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 already describes server_name as 'Exact canonical Census server name' with 100% coverage. The description reinforces the exactness requirement and connects server_name to the output concept of official_for, but adds no format or syntax detail 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 identifies the tool's purpose: returning contested identity information for one exact server_name, including official_for, name_collision_count, and up to 10 lookalike values. It is clearly distinct from a generic lookup or search, though it lacks an explicit verb like 'returns' or 'gets' and uses domain jargon ('contested identity').

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 the input is 'one exact server_name' and says it 'never invents lookalikes,' but it gives no explicit guidance on when to choose this tool over siblings like census_lookup or census_search. No exclusions or alternative conditions are mentioned.

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 burden. It discloses that this is a live lookup (implies read-only, non-destructive) and explicitly lists the flags and verdict it returns. It also notes the verdict is fact-based (healthy | issues | unknown). While it doesn't mention potential failure cases (e.g., unknown name), the return of 'unknown' hint at that. This is solid behavioral disclosure for a look-up 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, information-dense sentence that leads with the core purpose then lists the outputs. There is no filler, every clause adds useful detail, and the example is woven in naturally. It is efficient and easy to scan.

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 has only one required parameter, no output schema, and no annotations. The description fully covers purpose, input format, and the complete set of returned fields. Nothing critical is missing for an agent to invoke it correctly and interpret the result.

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% (the only param 'name' is described as 'Exact MCP registry server name'). The description adds value by giving a concrete format example ('io.github.owner/name') and stressing the need for exactness, which clarifies the expected input beyond the generic schema text. This is a meaningful enhancement over the 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?

The description clearly states the action ('Get... verdict') and the resource ('one MCP server by its exact registry name'). It concisely enumerates the returned fields (stars, recency, flags, collisions, verdict), which sets expectations and distinguishes it from sibling search/recent tools that do not target a single exact name.

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 specifies the key prerequisite: the caller must provide the exact registry name, with a concrete format example. It implicitly signals when to use this tool (when you already know the exact name) versus siblings like census_search or census_lookalikes, but it doesn't explicitly name those alternatives. The guidance is clear enough for correct selection.

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 read-only, idempotent, non-destructive behavior. The description adds useful context beyond those annotations: the result is 'exact' and 'immutable', tied to 'Preflight v1', and the operation is 'Unmetered.' This gives an agent meaningful operational expectations without contradicting the annotations.

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, tightly written sentence that front-loads the action and resource, then adds two useful qualifiers ('immutable' and 'Unmetered'). Every word earns its place and there is no redundant repetition of the schema or annotations.

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 zero parameters, an output schema, and annotations that fully describe the safety profile, the description is complete. It tells the agent exactly what will be listed, that the list is canonical and stable, and that the operation has no metering cost.

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 the baseline is 4. The description still adds value by specifying what the output will enumerate: policy objects, canonical ruleset, and digests, which helps the agent anticipate the returned content.

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 opens with a specific verb, 'List', and names a precise resource: 'exact immutable Preflight v1 built-in policy objects, canonical ruleset, and policy digests.' This clearly distinguishes it from the sibling census tools, which concern coverage, lookups, preflight checks, and watch operations.

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 usage by identifying the exact immutable policy catalog and adds an 'Unmetered' cost signal, but it does not explicitly name alternatives or state when to prefer this tool over siblings like census_preflight or census_lookup. Usage context is present, though exclusion/alternative guidance is left 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?

It adds meaningful behavior beyond the annotations: the return payload includes evidence reasons, freshness, digests, and explicit limits, and the refresh=if_stale path requires an x-api-key. Annotations already indicate the tool is not read-only, not idempotent, and not destructive, so the description supplements rather than contradicts them.

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 tight and front-loaded: outcome, scope, then a key auth constraint. Each sentence provides distinct, non-redundant 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?

With an output schema available and only one required parameter, the description covers the main invocation concerns: what the tool returns, its role as a preflight gate, and the special auth condition. The main remaining gap is clearer semantics for policy_id and refresh, but the overall definition is sufficient for selecting and invoking the tool.

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 only 33%, and only server_name is documented in the schema. The description partly compensates by explaining that refresh=if_stale requires an API key and that policy_id relates to a 'documented built-in install policy,' but the enum meanings for policy_id and refresh are still mostly left to inference.

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 ('Evaluate') and a clear object ('one exact MCP server under a documented built-in install policy'), and it defines the outcome categories (PASS, REVIEW, BLOCK). This separates it well from sibling census tools like census_lookup or census_policy_list.

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 explicitly frames this as 'a first gate, not a security audit,' giving the agent a clear sense of when in a workflow to use it. It does not explicitly name sibling alternatives, but the first-gate framing provides adequate selection context.

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 and does well: it discloses that the call is unmetered, that only rows with known first-seen dates are returned, and that it never fabricates or guesses discovery times. It does not describe errors or response details, but for a simple read-oriented list tool this is solid 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?

The description is three tight sentences with no filler. It front-loads the core purpose, then adds payload equivalence, metering behavior, data integrity guarantees, and parameter details. Every sentence 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 single-optional-parameter list tool, the description covers the essential selection and invocation details: what is returned, the ordering basis, the data-quality caveat, and the limit behavior. It relies on the GET /v1/recent reference for output shape, which is acceptable though not fully self-contained.

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%: the limit parameter is already documented in the schema. The description repeats the limit range and default without adding new semantic detail beyond that, so 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?

The description states a clear verb-like action: returning the newest MCP servers ordered by real first_seen_at, and references the exact payload shape via GET /v1/recent. This distinguishes it from siblings like census_search or census_stats without ambiguity.

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 provides clear context that this tool is for retrieving the latest discovered servers, ordered by real first_seen_at, and only includes rows with known discovery dates. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough to guide appropriate use.

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 full behavioral disclosure, and it does so well: typo resolution, disambiguation, known_brand handling, research/watchlist states, and the 'never invent servers' guardrail are all made explicit.

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?

Main purpose is front-loaded, and every sentence contributes: scope, return categories, result preference, and safety rule. The field list is dense but structured and free of 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 low-complexity 2-parameter search tool with no output schema, the description covers the important outcomes and edge behaviors. It could optionally describe the match object shape more concretely, but it is sufficient for an agent to invoke the tool correctly.

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%, so the baseline is 3, but the description adds concrete examples ('github', 'postgres'), clarifies partial-name matching, and reinforces typo resolution behavior, making the query parameter more actionable than the schema alone.

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 action and resource: 'Search MCP servers by keyword or partial name', with concrete examples and a clear result set. This is enough to distinguish it from exact-lookup and coverage-style siblings even without naming them.

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?

Implies usage: use this when searching for MCP servers by keyword or partial name. It gives strong post-return guidance ('Prefer official_match=true rows. Never invent servers') but does not explicitly say when to prefer census_lookup or other sibling tools, leaving alternatives 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 provided, the description carries the full behavioral burden. It does disclose the return content (preflight body plus stamp text and stamp_json), cost equivalence, and the PASS limitation. However, it does not mention potential side effects, caching behavior, idempotency, or what happens when refresh or policy_id change the result.

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?

Five concise sentences, each adding distinct value: scope, input parity, output, cost, usage rule, and a limitation. The most important information is front-loaded, and there is no filler or repetition of schema details.

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 lack of annotations and output schema, the description does a good job explaining the return value and cost. It covers what an agent needs to know about safety expectations (not a malware scan or permission review) and usage. Minor gaps remain around refresh semantics and stamp lifecycle, but overall it is substantially complete for this tool's complexity.

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 only 33%, so the description should compensate. It adds meaning for server_name ('exact canonical') and policy_id ('built-in policy'), but it leaves the refresh parameter entirely unexplained. The cross-reference to 'Same input as census_preflight' helps, but the tool's own description does not fully cover the parameter semantics.

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 the tool's purpose as producing a 'Census stamp for one exact MCP server under a built-in policy' and clarifies its relation to census_preflight. It identifies the specific resource (one MCP server) and the output format (CENSUS-STAMP/1 text plus stamp_json), which helps distinguish it from siblings. It lacks an explicit verb like 'stamps' but the name plus description make the intent 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?

'Never connect without a stamp' gives a concrete when-to-use rule, and 'Same input as census_preflight' plus 'Cost matches preflight' provide useful decision context. The caveat 'PASS is not a malware scan or permission review' sets expectations about limitations. It does not explicitly name alternative sibling tools or conditions for choosing them over this one.

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 bears full responsibility for behavioral disclosure. It adds valuable context: it is 'Unmetered', returns data from the live census, and explicitly states 'No invented metrics' (ensuring data provenance). It also lists the exact output fields. While it omits error handling, caching, or authorization details, these are less critical for a read-only stats tool, making this robust transparency.

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 two efficient sentences. It front-loads the core purpose, then adds the unmetered note and the complete output field list, with no redundancy or filler. Every sentence contributes essential 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 simple tool with no parameters and no output schema, the description is fully complete. It states the source (live census), the API equivalence, and enumerates every returned field including a timestamp (captured_at). An agent can invoke it without ambiguity, and the output is fully anticipated.

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, so the description adds no parameter-specific meaning. Per the rubric, 0 params sets a baseline of 4. The schema coverage for parameters is trivially complete (no properties), so this score is appropriate without further description.

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 tool returns 'Ecosystem headline numbers from the live census' and enumerates the specific metrics (total servers, healthy/issues counts, popular, remote-capable, github-linked, captured_at). It also references the exact payload format (same as GET /v1/stats). This is specific and not a tautology, though it does not explicitly differentiate from sibling census tools (e.g., census_coverage, census_lookalikes) – the name and field list imply its distinct role.

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 tool for quick summary stats by listing headline metrics and noting it is 'Unmetered', but it does not explicitly state when to use it vs siblings or provide exclusions (e.g., 'for detailed records, use census_lookup'). The guidance is understandable but left 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?

With no annotations, the description carries full burden for behavioral disclosure. It reveals that the operation is read-only by the verb 'List' and that authentication via x-api-key is required, which is useful beyond the schema. It does not address response format, filtering semantics, or rate limits, so behavioral transparency is adequate but shallow.

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: the primary action and object appear first, followed by the auth requirement. No filler or redundant restatement of the tool name.

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, no-output-schema listing tool, the description covers the core information: what is returned and the required credential. It could add a sentence about the response shape or per-server scope details, but this is an optional enhancement rather than a gap for basic invocation.

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 input schema has zero parameters and 100% description coverage, so the baseline is high. The only credential mentioned, x-api-key, is outside the parameter list and is appropriately surfaced in the description. There are no parameter semantics to clarify.

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 an explicit action ('List') and resource ('active per-server watches') with a scope qualifier ('for this API key'). The verb differentiates it from sibling tools like census_watch_subscribe and census_watch_unsubscribe, so an agent can select it unambiguously.

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 gives clear context for when to call it: whenever the agent needs the current active per-server watches associated with the API key. It also states the required credential ('Requires x-api-key'), which is essential usage guidance. It does not explicitly discuss alternatives or exclusions, but the list/subscribe/unsubscribe sibling split is inferable from the verb.

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 full behavioral burden and does well: it discloses auth requirements, real-observed-change semantics, event types, return payload (watch id + HMAC secret), signature header format, and free/pro tier limits. However, its 'Fires only on ...' list omits tools_changed, which is a valid event in the schema, so transparency is slightly incomplete.

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 six short sentences, each earning its place: purpose, event types, auth, delivery choice, return value, and rate limits. It is front-loaded and contains 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 subscription tool with no output schema, it covers the return value, signature verification hint, auth, delivery method, event types, and tier limits. The main gaps are the omitted tools_changed event and the lack of an explicit 'provide at least one of webhook_url or email' requirement.

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%, so the baseline is 3. The description adds only delivery preference (webhook over email) and optionality, which is useful but does not meaningfully expand parameter meaning beyond what the schema already explains.

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 opening sentence states a specific verb and object: 'Subscribe this agent (or a human email) to alerts for ONE specific MCP server.' It also names the exact event types and scope, making it immediately distinguishable from census_watch_list and census_watch_unsubscribe.

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 gives actionable guidance: prefer webhook_url (https) to receive POST callbacks, treats email as optional, and notes that x-api-key is required. It does not explicitly name alternatives such as census_watch_list or state that at least one delivery endpoint should be provided, so guidance is strong but not exhaustive.

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 behavioral burden. It usefully adds the ownership/auth requirement via x-api-key, which is not in the schema. However, it does not disclose side effects, reversibility, idempotency, or error behavior for a mutation-like operation.

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 no filler. The action is front-loaded and the auth constraint is stated in the second sentence, which is an appropriately compact structure.

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 tool with no output schema, the description covers the operation and a key ownership requirement. Minor gaps like idempotency or response behavior remain, but they are not critical for basic correct invocation.

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 id parameter is already described as coming from census_watch_subscribe. The description adds meaningful context by requiring that the x-api-key owns the watch, clarifying which id values are acceptable.

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 verb 'Deactivate' plus the resource 'a watch by id' clearly states the action and target. It is easy to distinguish from the sibling tools census_watch_subscribe and census_watch_list because it names the inverse operation 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 description clearly conveys that this tool is for deactivating a specific watch by its id. It does not explicitly name alternatives or exclusion conditions, but the operation is clear enough that an agent can infer when to use it.

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