mcp-shield

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

With no annotations provided, the description carries the full burden and succeeds well: it discloses the cost model ('$0.005 via x402, free with API key'), describes the return value structure ('score (0-100), letter grade...'), and mentions the evaluation methodology ('12-factor CoSAI-aligned'). Minor gap on rate limits or error conditions.

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 highly efficient sentences. The first establishes the action and inputs, the second details outputs and cost. Every clause provides unique information (purpose, parameters, return schema, pricing model) with zero 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?

Given the simple 2-parameter schema and lack of output schema, the description adequately compensates by detailing return values and certification methodology. It appropriately omits redundant parameter explanations but could mention that parameters are mutually exclusive/either-or.

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%, establishing a baseline of 3. The description mentions 'URL or npm package name' which aligns with the parameter names, but adds no additional semantic context (e.g., format requirements, validation rules) beyond what the schema already provides.

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 ('Look up') and resource ('trust score') and clearly distinguishes this from siblings like get_stats or scan_server by emphasizing 'trust score' and 'certification status' specifically.

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 mentioning the two lookup methods ('by URL or npm package name'), but provides no explicit guidance on when to choose this over siblings like scan_server or search_registry, nor does it mention prerequisites like needing an API key for free access.

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?

With no annotations provided, the description carries full disclosure burden. It effectively communicates the live/real-time nature of the operation, specifies the return format (12-factor CoSAI-aligned score, letter grade, findings), and discloses the payment model. Missing minor operational details like sync/async behavior or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three information-dense components in tight structure: action ('Trigger...'), returns ('Returns...'), and cost ('$0.25...'). Front-loaded with the core verb, zero redundant words, and the parenthetical cost notation efficiently conveys critical business logic without disrupting flow.

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 single-parameter input and absence of output schema, the description adequately compensates by detailing return values and security assessment methodology. Covers the essential 'what it does, what it costs, what it returns' triad for a scanning tool, though could mention idempotency or caching behavior.

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% with 'server_url' fully documented. The description references 'HTTP/HTTPS MCP server' which aligns with the parameter but adds no additional syntax details, format examples, or constraints beyond the schema definition. Baseline 3 is appropriate given schema completeness.

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 'Trigger' with clear resource 'live trust scan' and target 'HTTP/HTTPS MCP server'. The emphasis on 'live' effectively distinguishes it from sibling 'check_trust', implying real-time analysis versus cached/previous results.

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 implied usage through the 'live' qualifier and critical cost information ('$0.25 via x402, free with API key'), which guides authentication/payment choices. However, it lacks explicit when-to-use guidance versus 'check_trust' or exclusions for when not to scan.

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. Adds valuable behavioral detail about result ordering ('Certified servers appear first') not found in schema. However, lacks explicit confirmation that this is read-only/safe or details about response format/rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero waste: purpose first ('Search the CraftedTrust registry'), followed by filtering capabilities, then behavioral detail. Front-loaded with core action and appropriately sized for a 5-parameter search 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?

Given 100% schema coverage and rich parameter descriptions, description adequately covers tool purpose and key behavioral trait (sorting). Minor gap regarding return values (no output schema exists), but sufficient for a standard search operation pattern.

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%, establishing baseline 3. Description mentions filtering capabilities that map to grade, certified, and scan_type parameters, but adds no semantic meaning beyond what schema descriptions already provide (e.g., doesn't explain query syntax or enum value differences).

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?

Specific verb 'Search' + specific resource 'CraftedTrust registry' with clear scope ('4,200+ indexed MCP packages'). Distinct from siblings like check_trust, scan_server, and pay_for_certification which imply specific actions rather than browsing.

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 through describing filter capabilities ('Filter by grade, certification, or scan type'), but lacks explicit when-to-use guidance or named alternatives. Agent must infer suitability versus siblings like check_trust or scan_server based on tool names alone.

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