mcp-shield

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

No annotations are provided, so the description must fully convey behavioral traits. It only describes what is returned, not side effects, authentication requirements, rate limits, or idempotency. Since it's a lookup operation, more context on safety and limitations would be beneficial.

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 fluff. The first sentence states the purpose and inputs, the second lists outputs. Front-loaded and efficient.

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?

Despite no output schema, the description explains the return values. Given the simplicity of the tool (lookup with two optional parameters), the description is mostly complete. Minor gaps like response format or error handling are not critical for basic usage.

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 both parameters are described. The description adds minimal extra meaning ('by URL or npm package name') beyond the schema. It is adequate but does not significantly enhance understanding.

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 function: 'Look up the trust score for any MCP server by URL or npm package name.' It also lists the outputs: score, grade, findings summary, and certification status. This distinguishes it from sibling tools like scan_server and 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 implies usage for checking trust but does not explicitly state when to use this tool versus alternatives like scan_server or get_stats. No exclusions or prerequisites are mentioned, leaving some ambiguity.

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. It discloses what data is returned (server counts, trust scores, flagged count) but omits operational details like data freshness, caching behavior, or rate limiting.

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?

Single sentence structure front-loads the core action ('Get CraftedTrust ecosystem statistics') before the colon, followed by efficient enumeration of example metrics and 'and more' to indicate comprehensiveness without verbosity.

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 lacking an output schema, the description adequately compensates by listing specific example statistics returned. It could improve by indicating the response structure format, but sufficiently conveys content scope for tool selection.

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 contains zero parameters (empty properties object), establishing a baseline score of 4. The description correctly implies no filtering parameters are needed for this ecosystem-wide aggregation.

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 specific verb 'Get' with clear resource 'CraftedTrust ecosystem statistics', distinguishing it from sibling tools that operate on specific entities (check_trust, scan_server) or processes (pay_for_certification, verify_payment).

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?

While the description implies usage context by listing aggregate metrics (totals, averages), it lacks explicit guidance on when to use this versus search_registry for specific lookups or check_trust for individual verification.

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 mentions 'live trust scan' which suggests a non-destructive read operation, but does not elaborate on potential side effects, resource usage, or authorization needs. Returns data are listed, which adds some 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 a single clear sentence that is front-loaded and efficient. It could benefit from a slightly more structured format, but it wastes no 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?

With only one parameter, no output schema, and no annotations, the description provides most necessary context: what the tool does and what it returns. It does not clarify if the scan is synchronous or if there are rate limits, but for a simple tool it is adequate.

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 does not add further meaning beyond what the schema already provides for the single parameter 'server_url'.

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 ('trigger a live trust scan'), the resource ('HTTP or HTTPS MCP server'), and the outputs ('trust score, grade, and security findings'). It is specific and distinguishes from sibling tools like check_trust, get_stats, and 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 implies usage for security assessment but does not explicitly state when to use versus alternatives or mention any prerequisites, exclusions, or comparisons with sibling tools.

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 fails to disclose behavioral traits such as side effects (e.g., read-only), authentication requirements, or rate limits. It only states the basic function, leaving critical behavioral context unaddressed.

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 extremely concise at two sentences, with no filler. Every word is purposeful, and the key actions are front-loaded. This aligns well with the need for efficient communication.

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?

Despite covering the basic function, the description omits important context: output format (since no output schema), required parameters (query is required but not highlighted), pagination, and any usage constraints. For a tool with 5 parameters and no output schema, this is insufficient for confident 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?

All parameters are described in the schema (100% coverage), so the baseline is 3. The description adds minor value by listing filterable fields (grade, certification, scan type) but does not enhance understanding of the 'query' or 'limit' parameters beyond what the schema provides. Thus, it meets but does not exceed expectations.

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 searches the CraftedTrust registry overlay for indexed MCP packages and servers, using a specific verb ('Search') and resource ('registry'). It distinguishes from sibling tools (check_trust, get_stats, scan_server) which serve different purposes, making the tool's role unambiguous.

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 provides no explicit guidance on when to use this tool versus alternatives (e.g., check_trust, scan_server). It does not specify when not to use it or which contexts are appropriate, leaving the agent to infer usage from the purpose alone.

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