NORMA MCP Server

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

Annotations already declare readOnly and idempotent hints. The description adds the heuristic nature ('Indicative', 'Heuristic only') and indicates the output format (counts and slug examples). This goes beyond the annotations, though it does not detail limitations beyond the heuristic caveat.

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: the first front-loads the core function, and the second adds a necessary caveat and pointer to a more advanced tool. Every word earns its place, with no redundant or filler content.

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 no output schema, the description clarifies the return types (covered/partial/gap counts and slug examples) and the heuristic nature. It could have mentioned potential error scenarios or exactly how the heuristic works, but for a read-only, idempotent tool with 2 parameters, it is sufficiently complete.

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 provides 100% description coverage for both parameters, including details about the company_profile nested object and target_framework enum. The description states the high-level purpose but adds no new parameter-specific meaning beyond what the schema already defines, so the baseline of 3 is appropriate.

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 assesses compliance gaps, listing specific inputs (company profile, target framework) and the output (covered/partial/gap counts and slug examples). It uses a specific verb and resource, distinguishing it from siblings like generate_policy and map_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?

The description provides clear usage context: it is an indicative, heuristic tool, and it explicitly points to Pyxis for severity-ranked gap registers. However, it does not directly compare against sibling tools such as search_controls or map_controls, so it falls short of a full when/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?

The description adds useful context beyond the annotations: output format (Markdown), a not-legal-advice disclaimer, and template sourcing details (32 public vs 176 full). It aligns with idempotentHint=true by implying deterministic template parametrization, and no contradiction with readOnlyHint=false.

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, front-loaded with purpose, then corpus context and a usage hint. No extraneous words; each sentence adds distinct value.

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 nested parameter and no output schema, the description nails the essential behavior: input source, required discovery step, output format, and disclaimer. It could mention error behavior for invalid slugs, but overall it's well-rounded for an agent.

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 enriches company_context semantics by mentioning 'Variables substituted into {{COMPANY_NAME}}, {{SECTOR}}, etc.', which clarifies how the parameter is used. It also reinforces the template_slug discovery via search_controls.

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 verb 'Parametrize' with a specific resource ('NORMA compliance template') and output ('Markdown'). It distinguishes from siblings by explicitly directing users to search_controls for slug discovery, setting this tool apart as the generation step.

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?

Provides a clear prerequisite: use search_controls first to find a slug, which tells the agent when to call this tool (after discovery). It also frames the tool's role in a workflow but doesn't explicitly exclude alternatives like assess_gap or map_controls; however, the search_controls mention gives practical 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 provide readOnlyHint and idempotentHint, but the description adds valuable behavioral details: it operates on the 'cross_references' frontmatter graph and returns an array of mapped pairs with confidence and source slug. This goes beyond the annotations by explaining the underlying data source and output shape.

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 long, with the first stating purpose and mechanism and the second giving a usage example and output summary. It is front-loaded and free of unnecessary words, making it highly concise.

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 purpose, usage, mechanism, output type, and includes an example. Since there is no output schema, the description appropriately explains the return array and its fields. It does not mention error conditions or edge cases, but the tool is simple and read-only, so this is sufficient.

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 67%, and the description helps clarify the from/to frameworks using an example, but it does not mention the 'limit' parameter at all. The schema property descriptions are minimal ('Source framework', 'Target framework'), so the description adds some semantic value but does not fully compensate for the missing explanation of limit.

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 with a specific verb ('Crosswalk') and resource ('corpus controls between two compliance frameworks') via a specific mechanism ('cross_references frontmatter graph'). It also distinguishes itself from sibling tools like search_controls and assess_gap by focusing on mapping 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 concrete usage example ('I am ISO 27001 certified — what gaps for NIS2?') that illustrates when to use the tool. It does not explicitly mention when not to use it or compare with alternatives, so it lacks exclusionary guidance but still offers clear context.

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 readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable context by disclosing the return format (matching templates with title, framework, slug, source_refs, and excerpt) and the full-text scope. This goes beyond the annotations and schema, providing a clear picture of the tool's 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?

The description is two sentences, front-loaded with the main purpose, and includes no filler. It effectively balances brevity with necessary detail about filtering and return 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?

For a read-only search tool, the description is complete. It states what is searched, the filtering options, and the exact fields returned. Since there is no output schema, listing the return fields is especially valuable. The annotations cover safety, and the schema covers parameters adequately.

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 describes keyword and framework, with descriptions for both. The description adds the list of allowed framework values and confirms keyword matches title+body. However, the 'limit' parameter has no description in either the schema or the description, though its constraints (default 10, max 50) are present in the schema. Overall, the description partially supplements the schema but doesn't fully compensate for the missing 'limit' semantics.

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 ('Full-text search') with a clear resource ('the curated NORMA control corpus'), and explicitly mentions filtering by framework and the return fields. This clearly distinguishes it 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 clearly states what the tool does and mentions the framework filter as a usage option. However, it does not explicitly compare with sibling tools or state when not to use this tool, so it falls short of a 5. The purpose is clear enough that an agent would know to use it for full-text search of controls.

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