guard-core-mcp

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: snippets are verbatim from the README as of server build time with a re-check warning when release_status is untagged, unknown inputs return an error object rather than raising, and the tool is read-only static data that works without the Guard libraries installed.

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 and routing in the first two sentences, then behavior. The lengthy 'Returns' paragraph enumerates fields that an output schema already covers, so some content is redundant, but the README-drift caveat in it 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?

Given an output schema exists, the description covers everything else an agent needs: input semantics, error handling for unknown language/framework, data staleness caveats, and the zero-dependency read-only nature. 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% and both parameters are fully documented in the schema, including the error-on-unknown behavior and slug-or-package-name acceptance. The description restates rather than extends this, 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: 'Get the install command and a verified minimal integration for one Guard adapter.' It explicitly contrasts itself with siblings ecosystem (survey all adapters) and wire_agent (telemetry), so an agent can route correctly 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 an explicit trigger ('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'). This is textbook when-to-use/when-not 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, but the description adds substantial context they cannot carry: the sandbox guarantee (request never sent, enable_redis forced off so Redis is never touched), the graceful error-object behavior when guard-core is absent, and the important scoping caveat that this is detection alone, not the full middleware pipeline, so a clean verdict does not promise routing.

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-loads purpose and the sibling alternative, then layers guarantees, limitations and caps in descending order of importance. Four dense paragraphs is on the long side, but each sentence carries distinct decision-relevant information rather than restating the schema.

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?

Although an output schema exists, the description covers everything else an agent needs: error-mode behavior, the fact that caps and enhanced detection require guard-core 3.15.0 (with `versions` named to check), and the boundary between a detection verdict and a real pipeline block. Nothing material is missing for a zero-required-param 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 coverage is 100%, so baseline is 3; the description goes beyond it by naming specific SecurityConfig fields reachable through the `config` override (detection_max_scan_values default 512, detection_max_scan_chars default 65536, detection_max_json_depth default 32) and their truncation semantics, which the schema only gestures at with a generic example.

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+resource (run one synthetic request through guard-core's real penetration-detection engine) and immediately distinguishes itself from the sibling it overlaps with: 'Use validate_config instead to check a config, not a request.' An agent can route between the two 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 an attack payload is caught; explain why a benign request was flagged) and an explicit exclusion pointing at validate_config for config checks. Nothing about when-to-use 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 the read-only, idempotent, closed-world profile, but the description adds real behavioural detail beyond them: the graceful failure mode ('returns an object with an error key instead of raising') when the library is missing or the package is unrecognized, and the spelling-fallback behaviour of matches. Return-shape detail partially duplicates the output schema, which keeps this just short of a 5.

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 guidance, then return/error semantics. Every sentence carries information an agent needs; no filler or restatement of the title.

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?

Complete for a two-parameter lookup tool: purpose, sibling routing, match semantics, fallback behaviour, and error handling are all covered, and an output schema exists so return values need not be exhaustively restated.

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 matching semantics the schema does not spell out: 'every other field whose name or description contains every word of the query' (AND-of-words) and the spelling-based fallback when nothing matches. That is genuine meaning beyond the enum-like examples in 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?

States a specific verb and resource ('Find a Guard config setting') and immediately scopes it by name-or-behaviour, with the returned payload (type, default) named up front. It explicitly distinguishes itself from validate_config and search_docs, so an agent can pick it without opening sibling schemas.

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 both when-to-use cases ('learn what a setting means, or whether a setting for some behaviour exists at all') and names two alternatives with the exact conditions that select them: validate_config for checking a whole config, search_docs for prose explanations.

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 safety (readOnly, idempotent, non-destructive, closed-world), but the description goes well beyond them: it explains the release_status enum semantics (published/tagged/untagged) with the caveat that notes must be read together with it, and confirms it works without the Guard libraries installed. This is exactly the kind of domain 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 purpose and the usage routing before the detailed return-shape walkthrough. Reasonably sized for the information conveyed, though the returns block is long and could be tightened slightly without losing meaning.

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 output schema exists, so return values need not be fully explained, yet the description still gives the agent a precise map of the registry structure and the release_status semantics it needs to interpret results correctly. Complete for a zero-param read 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?

There are zero parameters, so the baseline is 4. The description confirms 'It takes no arguments', which is a useful restatement of the empty schema but adds no further parameter meaning because none exists.

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 and resource ('Survey the whole Guard ecosystem: every language, engine, adapter and agent') and enumerates exactly what the registry contains. It explicitly distinguishes itself from siblings adapter_setup and wire_agent by describing when those should be used instead.

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 ('resolve a package name or compare languages') and when-not-to-use ('When you already know the language and framework, use adapter_setup ... or wire_agent ... instead, which return less'). Names the alternatives and the condition that selects them.

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, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds real behavioral context: exact error semantics (unknown package and nonexistent path both return {"error": "unknown doc path"} and are indistinguishable), offline operation, and the scope limit that it cannot read outside bundled docs.

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 paragraphs, front-loaded with the purpose, then routing guidance, then return shape, then edge cases. Every sentence carries information an agent needs; there is 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?

Despite an output schema existing, the description usefully names the returned fields and documents the failure case, plus scope constraints. Nothing needed to invoke it 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 description coverage is 100%, so the schema already documents both parameters and the baseline is 3. The description adds provenance semantics beyond the schema ('the package and path come from a search_docs result'), which helps the agent source correct values.

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 ('Return the full text of one bundled Guard documentation page') and immediately distinguishes itself from the sibling search_docs by noting 'it does not search'. An agent can tell this apart from 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?

Explicitly states when to use it ('after search_docs when a snippet is not enough') and names the alternative it is not. It also tells the agent where the required arguments come from (a search_docs result), removing the main selection 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?

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the search is offline over bundled docs, an unrecognized package silently matches nothing rather than erroring (unlike validate_config), and therefore an empty result is ambiguous and package should be dropped before concluding a docs gap. That failure-mode guidance is exactly what annotations cannot express.

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 one-line purpose, then routing, then return shape, then caveats. Every sentence carries information, though the final retry instruction is dense and could be trimmed into the package sentence it repeats.

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 output schema exists, yet the description still states the return surface (query, results with package/path/heading/snippet/url/score) and the handoff path to get_doc. Combined with routing rules and the empty-result interpretation, an agent has everything needed to call and interpret this 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 100% – limit, query and package each carry descriptions, examples and defaults, including the package silent-match caveat. The description restates the package trap but adds no syntax or format 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 ('Search the bundled Guard documentation and return ranked, citable pages') and immediately scopes it as the docs shipped inside this package. It names the siblings it is not (config_fields, adapter_setup, wire_agent) and the sibling it feeds (get_doc), so an agent can separate it from the other nine tools 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?

Explicit routing: use it for how/why questions from documentation and to locate a page for get_doc; use config_fields for a setting's type and default; use adapter_setup or wire_agent for install and wiring steps. That covers when-to-use and named alternatives in one sentence.

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?

Goes well beyond the readOnly/idempotent annotations: it states validation happens in memory and is never applied, explains that pydantic silently ignores unknown keys so typos fail without error, enumerates what construction_warnings captures, and documents the failure path when the library is missing or package unrecognized.

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?

Purpose and the routing rule are correctly front-loaded, but roughly half the text enumerates the return payload (valid, package, version, model, errors, unknown_fields, deprecated, construction_warnings) even though an output schema already exists. That enumeration distends the definition without adding new executable guidance.

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 an output schema and full annotation coverage, the definition closes every meaningful gap: usage routing, non-destructive in-memory semantics, the silent-unknown-key trap, and error behavior on missing/unknown package.

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 schema already documents both parameters, but the description adds real meaning on the package parameter's failure mode ('Any other value returns an error object', missing-install hint) and frames config as constructor-shaped input.

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 explicitly differentiates from the sibling config_fields. An agent can distinguish it from check_payload, ecosystem, or config_fields 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 two concrete use cases ('confirm a config is valid' or 'find out why a setting seems to have no effect') and names the alternative (config_fields) with the exact condition that selects it ('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, read-only, idempotent call, and the description goes well beyond them: it names the returned fields, explains that a null installed version means the library is absent and downstream answers would be guesses, and clarifies that an installed/docs version mismatch is normal and harmless.

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 core instruction is front-loaded in the first line ('Report which Guard libraries... Call this first'), followed by return-field semantics. It runs three paragraphs and could be slightly tighter, but each block carries distinct decision-relevant 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?

Even though an output schema exists (so return values need not be documented), the description supplies the interpretation rules an agent needs: null-version consequences and docs-vs-install divergence. Nothing required to call it or act on its 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?

The schema has zero parameters at 100% coverage, so the baseline is 4. The description reinforces this with 'It takes no arguments', but there is no additional parameter meaning to convey.

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: reports which Guard libraries the server can introspect and at which version. It differentiates itself from siblings by framing itself as the version-provenance precondition rather than a config/payload validator.

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 tells the agent when to call it ('Call this first, before trusting any answer about a version-specific feature') and ties its outcome to sibling behavior, explaining that validate_config, config_fields and check_payload cannot answer for a library whose installed version is null.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: unknown language/framework returns an error object rather than raising, and the data is static and readable without libraries installed. It stops short of describing pagination or caching, which is minor here.

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-loads purpose and the alternative in the first two sentences, then details returns. The return enumeration is somewhat redundant given an output schema exists, which costs a point, but the structure is clean and nothing is misleading.

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-only lookup with full schema coverage and an output schema, the description covers purpose, alternative routing, error behavior, and offline availability. An agent has everything needed 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 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining what the framework parameter changes downstream: for python the note points at the bundled guard-agent adapter doc, while for other languages the agent is standalone and the note says so. It also reiterates the error behavior for unknown values, reinforcing the schema's constraint.

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 ('Get how to set up the Guard telemetry agent for one language') and explicitly separates itself from the sibling adapter_setup. An agent can distinguish this from adapter_setup, search_docs, or get_doc 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 ('ship security events and metrics to the guard-core-app backend') and names the alternative with its selection condition ('Use adapter_setup instead for the request-blocking middleware itself'). Also states the precondition that it works without the Guard libraries installed.

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