guard-core-mcp

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

Annotations cover the safety profile (read-only, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses provenance/staleness of snippets ('reflect the README at the time this server was built; when release_status is untagged, re-check the repository'), error behavior instead of raising, and that no Guard libraries need be installed. That is exactly the extra context annotations cannot carry.

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?

Front-loaded with the core action, then usage routing, then return details. Every sentence carries information, though the multi-line return inventory overlaps with the output schema that already exists, so it is slightly longer than strictly necessary.

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?

An agent has everything needed: what it returns, when it errors, how fresh the data is, and that no dependencies are required. Because an output schema exists, the extra return prose is bonus rather than obligation, and nothing material 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?

Schema description coverage is 100%, so language and framework are already fully documented, including allowed values and error-on-unknown behavior. The description only reinforces that the pair selects a single adapter and that unknown values yield an error object, which duplicates rather than extends 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?

Specific verb+resource: 'Get the install command and a verified minimal integration for one Guard adapter.' The scope ('one Guard adapter', keyed by language+framework) is stated precisely and clearly distinguishes it from the survey tool (ecosystem) and the telemetry tool (wire_agent).

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?

Explicit when-to-use ('when you know the language and web framework and want working setup code') plus named alternatives with their selecting conditions: 'Use ecosystem instead to survey every adapter, and wire_agent to set up telemetry.' Nothing 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?

Annotations already cover the safety profile (readOnly, non-destructive, idempotent, closed-world), but the description adds substantial context beyond them: sandboxed execution, request never sent, enable_redis forced off, graceful error-object behavior when guard-core is missing, and the crucial scope caveat that this is detection alone and a clean verdict does not guarantee the request reaches the route.

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?

It is on the longer side, but it is front-loaded with the core action, and the warning paragraph about pipeline scope and the cap paragraph each carry distinct, non-redundant information an agent needs to interpret a verdict. Only the version-availability detail feels slightly peripheral.

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 annotations, a full input schema, and an output schema present, the description still proactively explains the return shape (is_threat, trigger_info, threat_categories, threat_scores, elapsed_ms) and the error path, so nothing needed to call or interpret the tool correctly 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?

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that config overrides force enable_redis off and by naming the detection_max_scan_values/chars/json_depth caps that govern how payloads are judged. It stops short of walking each parameter, but the added semantic layer exceeds 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 first sentence states a specific verb and resource: run one synthetic request through guard-core's real penetration-detection engine. It is unambiguous and immediately distinguishable from the config-checking sibling it names.

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 gives two explicit use cases ('confirm that an attack payload is caught' or 'explain why a benign request was flagged') and routes the agent away from this tool with 'Use validate_config instead to check a config, not a request.' When-to-use and the alternative are both 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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely non-obvious behavior: exact is null when no exact match, matches falls back to 'closest field names by spelling' when nothing matches, and an error key object is returned instead of raising when the library is missing or the package is unrecognized. That error-vs-raise contract is the kind of detail an agent cannot infer from 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?

Front-loaded with purpose, then usage, then return semantics, then error behavior — a clean progression with no filler. It does spend a sentence enumerating return fields that the output schema already covers, which is mild 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 read-only lookup with an output schema and full annotation coverage, the description supplies the missing pieces: the error-object contract and the spelling-fallback behavior for matches. An agent has everything it needs to call this correctly and interpret failure modes.

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%, so both query and package are already documented, including case-insensitivity and word order. The description restates the exact-name-vs-words behavior but adds little syntax or constraint detail beyond the schema, so the baseline 3 applies.

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 and resource ('Find a Guard config setting by name or by what it does, with type and default'), and immediately differentiates itself from validate_config and search_docs. An agent can tell exactly what this returns without opening the schema.

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?

Explicitly names the two alternatives and the condition that selects each ('Use validate_config instead to check a whole config you already wrote, and search_docs for prose explanations rather than field metadata'). It also states the discovery use case ('whether a setting for some behaviour exists at all').

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 declare this a read-only, idempotent, closed-world operation, but the description goes well beyond them: it enumerates the returned structure, explains the release_status enum semantics (published/tagged/untagged) and the caveat that Go/PHP/Rust registry publishing lags tags, and states it works with or without the Guard libraries installed. No contradiction with the read-only hints.

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?

Front-loaded with purpose, then routing, then return shape, then the release_status nuance — a sensible order. It is on the long side and the release_status paragraph is dense, but nearly every sentence carries task-relevant information rather than restating structured fields.

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 a rich output schema, the description summarizes the registry shape and the non-obvious release_status/notes interaction an agent needs to interpret results correctly. For a zero-argument, read-only survey tool, nothing material 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?

Zero parameters, so per the rubric the baseline is 4. The description even reinforces this ('It takes no arguments'), leaving nothing about invocation ambiguous.

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 and resource ('Survey the whole Guard ecosystem: every language, engine, adapter and agent') and explicitly scopes itself apart from siblings by naming adapter_setup and wire_agent and the condition that selects them. An agent can distinguish this from the other eight tools without opening any schema.

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?

Gives explicit when-to-use ('resolve a package name or compare languages'), a hard constraint ('takes no arguments'), and named alternatives with the reason to prefer them ('which return less'). This is textbook routing 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description goes further by disclosing the exact failure contract ("An unknown package or a path that does not exist returns {\"error\": \"unknown doc path\"}; the two cases are not distinguished") and the offline/no-filesystem-escape boundary. These are non-obvious behavioral traits an agent cannot infer from structured fields.

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 short sentences, front-loaded with purpose, then usage, then return shape, then error/boundary behavior. Slight redundancy between "it does not search" and the framing of the tool as a retrieval-by-exact-path operation, but no sentence is wasted.

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 two-parameter read tool with an output schema and full annotations, everything an agent needs is present: how to obtain arguments, what comes back, what failure looks like, and the offline/scope boundary. Return-value detail that the output schema already covers is not required, and the description's listing of fields is just convenient reinforcement.

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 a real coupling constraint: both arguments must be taken from a prior search_docs result, which tells the agent not to invent values. It does not add format or syntax detail beyond the schema's examples, so it stops short of a 5.

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 verb+resource ("Return the full text of one bundled Guard documentation page") and immediately contrasts with the sibling it is most likely confused with: "it does not search" distinguishes it from search_docs. An agent can pick between get_doc and search_docs without opening either schema.

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?

Gives an explicit sequencing rule ("Use this after search_docs when a snippet is not enough"), states the negative case ("it does not search"), and explains where the arguments originate ("The package and path come from a search_docs result"). This is a complete when/when-not/alternative statement.

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/offline-safe semantics, but the description adds failure-mode behavior the annotations cannot express: an unrecognized package silently matches nothing, an empty result set is ambiguous between a real doc gap and a typo, and the recommended recovery is to retry with package omitted. It also contrasts this with validate_config's error 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?

Front-loaded with the core action, then routing, then return/parameter mechanics, then edge-case behavior. Each paragraph earns its place, though the return-field enumeration partially duplicates the output schema and makes it slightly longer than strictly necessary.

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 3-parameter search tool with an output schema and full annotation coverage, the description covers selection, alternatives, result handling, and the tricky silent-empty-result case. An agent has everything needed to invoke it correctly and interpret its output.

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, and the description adds genuine value beyond the schema by explaining that query terms are ranked by occurrence (hence 'use specific terms') and by giving an operational rule for the package parameter when results come back empty. It does not restate the limit parameter's meaning, so it stops short of a 5.

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 and resource ('Search the bundled Guard documentation') plus the return shape ('ranked, citable pages'). It also explicitly differentiates itself from siblings get_doc, config_fields, adapter_setup, and wire_agent by naming the question types each handles.

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?

Gives explicit when-to-use ('how or why questions from documentation'), a paired follow-up tool (get_doc to read the full page), and concrete when-not-to-use routing ('Use config_fields instead for a setting's type and default, and adapter_setup or wire_agent for install and wiring steps'). Nothing is 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?

Annotations already declare read-only, idempotent, non-destructive, but the description adds substantial behavior beyond them: validation happens in memory and the config is never applied, pydantic silently ignores unknown keys so misspellings fail silently, construction_warnings enumerates guard-core's logged-not-raised misconfigurations, and non-missing-library errors return an object with an error key instead of raising. This is exactly the kind of runtime context annotations cannot convey.

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?

Front-loaded with the core purpose, then usage, then returns, then error behavior — a sensible order. The one inefficiency is the paragraph enumerating every return field (valid, package, version, model, errors, unknown_fields, deprecated, construction_warnings) when an output schema already exists, which makes it longer than strictly necessary.

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 two-parameter validation tool with nested config input and an output schema, the description covers purpose, routing, safety, silent-failure semantics, and error paths. Nothing an agent needs in order to call it correctly or interpret a surprising result 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?

Schema coverage is 100%, so both parameters are already documented, which sets a baseline of 3. The description goes further by clarifying what a valid 'config' represents (exactly what you would pass to the model's constructor) and by explaining the failure mode when 'package' is unrecognized, which the schema does not state.

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 and resource ('Check a Guard config dict against the installed library's real pydantic model') and immediately differentiates itself from the sibling tool config_fields, which it names explicitly. An agent can pick between validate_config and config_fields without opening either schema.

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?

Gives two concrete use cases ('confirm a config is valid' / 'find out why a setting seems to have no effect') and an explicit routing rule to the alternative ('Use config_fields instead when you do not yet know the setting's name'). Nothing is 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?

Annotations already declare a safe, idempotent read, but the description goes beyond them by interpreting results: a null installed version means the library is absent and other tools would be 'guessing,' while a version mismatch between installed and docs_bundled_for is explicitly called normal. This is unusually rich disclosure of what the output means in practice.

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 key routing instruction is front-loaded in the first sentence and the field-by-field explanation follows logically. It runs long across several blocks and some return-field detail could be tightened, but every paragraph carries usable meaning rather than 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 zero-argument introspection tool with an output schema and full annotation coverage, the description supplies everything an agent needs: when to call it, the returned fields, and how to interpret null versus mismatched versions. No gaps remain for 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?

The tool takes zero parameters, which sets a baseline of 4. The description confirms 'It takes no arguments,' matching the empty schema, though there is nothing further to add.

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 and resource: reporting which Guard libraries this server can introspect and at which version. This is clearly distinct from siblings like validate_config, config_fields, and check_payload, which it names as dependent on the result.

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?

Explicitly says to 'Call this first, before trusting any answer about a version-specific feature,' and explains the downstream consequence: when a library is absent, validate_config, config_fields and check_payload cannot answer for it. When-to-use is stated directly rather than inferred.

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 declare readOnly/idempotent/non-destructive/closed-world, and the description goes further: it states the tool is read-only static data, works without the Guard libraries installed, and that unknown languages/frameworks return an error object rather than raising. That error-contract disclosure is exactly the kind of behavior an agent needs beyond 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?

Front-loaded with the core purpose and the sibling routing, then structured into usage and return-shape. It is on the long side and enumerates return fields that an output schema already carries, so it is slightly over budget rather than maximally tight.

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 present, the description does not need to enumerate return values, yet its usage guidance, error-handling contract, dependency note, and sibling routing leave nothing essential missing for 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%, so baseline is 3; the description still adds meaning by explaining the framework parameter's effect (python note points at the bundled guard-agent doc page, other languages are standalone and the note says so). That clarifies output implications of the parameter rather than merely restating it.

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?

Starts with a specific verb+resource (get the setup for the Guard telemetry agent) and immediately scopes it to 'one language'. It names the sibling adapter_setup and states the boundary between them, so an agent can distinguish the two without opening a schema.

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?

Gives the use case ('ship security events and metrics to the guard-core-app backend') and names the alternative ('Use adapter_setup instead for the request-blocking middleware itself'), which is an explicit when-to-use/when-to-use-something-else rule.

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