registry

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

With no annotations provided, the description fully bears the burden of disclosure. It details the returned record fields (identity verification, risk grade, auth posture, freshness, tool surface riskiest-first) and reveals side-effect behavior: unknown servers are queued for scanning by the call itself, requiring re-check. No contradictions.

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?

Four sentences, front-loaded with purpose and inputs, followed by return details and behavioral note. No fluff, every sentence adds 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 no output schema and one parameter, the description adequately explains inputs, outputs, and post-call behavior. It covers the workflow and edge case (unknown server). Minor gap: could mention possible error conditions.

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 description adds context (e.g., '@acme/mcp-server' example) and purpose but does not significantly extend beyond the schema description. 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 clearly states the tool checks an MCP server against the PolicyLayer registry, specifies accepted input formats (slug, npm package, URL, name), and distinguishes from sibling tools (check_mcp_stack, check_tool) by focusing on a single server.

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 says to use this tool 'BEFORE installing or allowing' a server, providing strong usage context. It also mentions that unknown servers are queued for scanning and to check back, which guides follow-up actions. However, it does not explicitly exclude scenarios where alternative tools (e.g., check_mcp_stack) would be preferred, though sibling names imply differentiation.

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 provided, so description carries full burden. It transparently details candidate resolution order, return contents (records, verdict, status), and rate-limit cost, with no contradictions.

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 with no wasted sentences, though it could be more structured (e.g., bullet points). Every sentence adds 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 no output schema, description adequately explains return values (records, verdict, lookup status) and constraints. Lacks mention of error handling but is otherwise complete for the 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 coverage is 100% but description adds meaning: explains candidate types (npm, registry slug, URL), order tried, and the 'name' field as a label, significantly enriching 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 tool checks a whole MCP stack (multiple servers up to 25) against the PolicyLayer registry, returning records for hits and status for misses. It distinguishes from sibling 'check_mcp_server' which likely handles single servers.

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 batch usage for multiple servers and mentions rate-limit cost, but lacks explicit when-to-use vs alternatives (e.g., 'use check_mcp_server for single servers').

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 implies this is a read-only query tool (returns classification), but it does not explicitly state that it has no side effects or that it is idempotent. With no annotations, this is a minor gap.

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 sentences, front-loading the key purpose and immediately providing a usage example. No unnecessary words.

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 description covers the tool's purpose, usage context, and output fields well. It could mention error cases (e.g., tool not found) but is adequate for the tool's simplicity.

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?

Input schema covers both parameters with descriptions. The tool description does not add new insights beyond the schema, and with 100% coverage, the baseline of 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 clearly states the tool returns a risk classification for a single tool, distinguishing from siblings like check_mcp_server (server-level) and check_mcp_stack (stack-level). It specifies the output contents and provides a concrete usage example.

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 says 'Use when deciding whether to allow a specific tool call' and gives an example, providing clear context. However, it does not mention when not to use it or specify alternative tools for different scenarios.

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 bears full responsibility. It discloses authentication and cursor-based pagination, but lacks details on rate limits, error handling, or the return structure of events. It is adequate but not comprehensive.

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 concise (two sentences) and front-loaded with purpose and key features. Every sentence provides valuable information without 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?

Given the lack of output schema, the description should describe return event structure for agent consumption. It lists event types but not the full schema. The tool's behavior and prerequisites are well-covered, making it adequate 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?

The input schema fully describes all three parameters with 100% coverage. The description adds minimal extra semantics beyond reinforcing the cursor concept for after_id. The schema carries the explanatory burden.

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 specifies the tool's purpose: it retrieves the registry change feed, listing specific event types (drift, auth flips, etc.). It uniquely identifies the resource and action, distinguishing it from sibling tools that check servers/stack or search registry.

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 mentions cursor-based pagination for resuming and requires a Registry Licence key with a link to obtain one. While it doesn't explicitly exclude alternatives, the sibling tools are sufficiently different, and the context implies usage for polling change events.

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?

Discloses return fields (risk grade, identity confidence, tool count) and explains the meaning of 'mismatch'. No annotations, so description carries full burden; sufficiently transparent for a read-only search 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 sentences, front-loaded with purpose, no wasted words. Every sentence contributes 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 no output schema, the description fully explains return values and follow-up action. Completely adequate for a search tool with 2 parameters and clear sibling 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?

Adds meaning beyond schema by explaining that query is matched against name, slug, and packages, and that limit controls max matches. Schema already describes parameters, but description adds context.

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?

Clearly states it searches the PolicyLayer registry by name, slug, or package substring. Distinguishes from sibling tools by explicitly mentioning follow-up with check_mcp_server.

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?

Provides explicit follow-up action (check_mcp_server) for the intended match, giving context on when to use this tool versus alternatives. Lacks explicit when-not but the context is clear.

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