NORMA MCP Server

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

Annotations already declare readOnlyHint and idempotentHint, indicating safe read-only behavior. The description adds important context: it is 'Indicative' and 'Heuristic only', warning that results are not authoritative. This goes beyond annotations to set proper expectations without contradiction.

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 concise sentences: the first states the core function, the second explains limitations and output. No filler words, and critical information is front-loaded. Every sentence 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?

The description sufficiently explains input, output (counts and slugs), and limitations. While missing explicit error handling or edge cases, for a heuristic tool with good annotations and schema coverage, it is complete enough for an agent to use 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 description coverage is 100%, so baseline is 3. The description adds value by explaining the output—'return covered / partial / gap counts and slug examples'—which is not detailed in the schema (no output schema). This enhances understanding of what the parameters produce, justifying a 4.

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 purpose: 'Assess compliance gap against a target framework'. It specifies the action (assess gap), resource (target framework), and input (company profile). This distinguishes it from siblings like generate_policy, map_controls, and search_controls, which handle different compliance tasks.

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 'Heuristic only' and directs users to Pyxis for a comprehensive severity-ranked gap register with FCI/WMI/ECI scoring. This gives clear context on when to use this tool (quick heuristic) versus when to use the alternative (detailed analysis), fulfilling the dimension criteria.

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 (readOnlyHint=false, idempotentHint=true) are not contradicted. Adds context: output is Markdown with a not-legal-advice disclaimer, templates from curated corpus. Could additionally note idempotency but still strong.

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, zero waste. Front-loads key action (parametrize template) and ends with critical usage instruction. Every sentence 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?

No output schema, but description details output (Markdown, disclaimer). Parameters fully explained. Mentions template corpus scale. All context needed for correct invocation is present.

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?

100% schema coverage baseline 3. Description adds: slug must be from search_controls, examples, and company_context variables are substituted into placeholders like {{COMPANY_NAME}}.

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?

Clear verb+resource: parametrize NORMA template with company context, return Markdown. Distinguishes from siblings by specifying prerequisite discovery via search_controls.

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 directs to use search_controls first to discover slug, providing clear prerequisite. Does not explicitely state when not to use or compare with assess_gap/map_controls, but guidance is sufficient.

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=true and idempotentHint=true. The description adds behavioral context by stating the return format ('Returns an array of mapped pairs with confidence + source slug') and the underlying mechanism (cross_references graph). This exceeds annotation-only information.

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 compact (two sentences) and front-loaded with the core action. Every sentence adds value, with no wasted 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 explains the return format in absence of an output schema and provides a contextual example. However, it could more explicitly differentiate usage from sibling tools like assess_gap or search_controls.

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 67% (only limit lacks a description). The tool description does not add any parameter-level details beyond what the schema provides. The parameters are self-explanatory given enum values, but no extra meaning is contributed.

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 purpose: 'Crosswalk corpus controls between two compliance frameworks via the cross_references frontmatter graph.' It uses a specific verb (crosswalk) and resource (controls), and distinguishes itself from siblings like assess_gap and generate_policy by focusing on mapping controls between frameworks.

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 a useful example prompt ('I am ISO 27001 certified — what gaps for NIS2?') that implicitly guides when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among 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?

Annotations already indicate read-only and idempotent behavior. The description adds useful details about return fields (title, framework, slug, source_refs, excerpt) and filtering capability, providing behavioral context 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?

The description is two sentences, front-loaded with the core purpose, and each sentence serves a distinct role (action + filters, return format). No redundant 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?

The description covers the tool's purpose, filtering capability, and return fields. While no output schema exists, the listed fields provide adequate completeness for a search tool. Minor gap: does not specify sorting or pagination, but acceptable for this complexity level.

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?

With 67% schema description coverage, the schema itself explains keyword and framework. The description reiterates the framework list but does not add new semantics for any parameters. The limit parameter is not described, though its default/min/max provide partial meaning.

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 performs full-text search on the NORMA control corpus, using a specific verb 'search' and a defined resource. It effectively distinguishes itself from sibling tools like assess_gap, generate_policy, and map_controls, which serve different purposes.

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 indicates when to use the tool (to search controls) and mentions filtering by framework, but does not explicitly state when not to use it or compare to alternatives. The implied usage context is clear given the distinct purpose compared to siblings.

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