digital-compass-mcp

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

Annotations already declare readOnly, idempotent, and non-destructive. Description adds valuable behavioral context: deterministic keyword matching (not guessing), returns top 3 matches with score. No contradictions.

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 sentences, front-loaded with action and method. Every sentence adds value: what it does, how it works (deterministic), and what it returns. No waste.

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 no output schema, description explains return value (best 3 matches with score) and matching behavior. For a 2-param tool with simple semantics, this fully covers what an agent needs to know.

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. Description does not add parameter-specific details beyond what the schema already provides; it repeats the query intent but adds no new semantic depth for parameters.

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?

Description clearly states it matches user-described situations to playbooks using deterministic keyword matching. It distinguishes from siblings like compass_list_situations (which lists all) and compass_get_content (which retrieves full content).

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 use when user describes a situation in their own words, and mentions deterministic matching to set expectations. Lacks explicit when-not-to-use or comparison to sibling tools like compass_list_situations for browsing, but context is generally clear.

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, and destructiveHint, covering safety and idempotency. The description adds behavioral context by specifying that the tool exposes the date of last editorial review, which goes beyond the annotations by detailing what information is provided.

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 a single sentence that packs all necessary information: what is returned (date of last editorial review), for what (every playbook and guide), and the purpose (transparency about freshness). 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?

For a simple, read-only tool with no parameters and no output schema, the description sufficiently explains the return value (date of last review) and the scope (all playbooks and guides). It is complete enough for an agent to understand what the tool does without further clarification.

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 no parameters and 100% schema description coverage, the description does not need to add parameter semantics. The baseline for zero parameters is 4, and the description appropriately focuses on the tool's output rather than 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?

The description clearly states the tool returns the date of the last editorial review for every playbook and guide, emphasizing transparency about freshness. This distinguishes it from sibling tools that focus on retrieving playbooks, content, situations, or channel reports.

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 when freshness information is needed, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context of 'transparency about how fresh the advice is' gives implied 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 and idempotent; description adds that it returns full markdown with specific structure (steps, not-to-do, etc.) and document order, providing behavioral insight beyond 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?

Two sentences that are front-loaded with the core purpose and usage hint. Every word earns its place; no 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?

Adequately describes the tool's purpose and output for a simple content retrieval tool. Could mention potential length of content, but the existing description is sufficient given the schema and annotations.

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 complete descriptions. The description mentions 'slug from compass_list_situations' but adds minimal extra value beyond schema. Baseline 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?

Clearly states it returns the full markdown of a playbook or guide, and describes the content structure. Distinct from sibling tools that list or find playbooks.

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?

Indicates that the content is suitable to relay step by step in document order, implying when to use. Lacks explicit when-not-to-use or alternative tools, but the context is clear.

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, and destructiveHint. Description adds context about public Romanian guide and multilingual content but does not contradict annotations or add critical behavioral details beyond them.

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 sentences, front-loaded with main purpose, no filler. Every sentence adds 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?

Given simplicity (1 optional param, no output schema), description adequately covers purpose and usage context. Could briefly mention output format, but annotations compensate.

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 has 100% coverage with an enum description for 'lang'. The description does not add extra meaning beyond what the schema 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 clearly states it lists all digital-crisis situations and prevention guides, with slugs for compass_get_content. It distinguishes from sibling tools by specifying its role as a listing tool for scenario discovery.

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?

Implied usage for listing available situations, but no explicit guidance on when to use alternatives like compass_find_playbook for searching or compass_get_content for retrieval.

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?

Description adds behavioral context beyond annotations: explains country-specific anchoring (e.g., lang=ro channels for Romania, lang=pl for Poland) and deduplication behavior when slug is omitted. Annotations already declare readOnlyHint, idempotentHint, destructiveHint. No 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 sentences, concise and front-loaded with purpose. No wasted words; every part adds clarity.

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 0 required params, low complexity, and no output schema, the description covers expected behavior (country-specific channels, deduplication). Could mention output format, but not critical for a list-like return.

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. Description adds value: clarifies lang determines country-specific channels with examples, describes slug filtering, and mentions deduplication behavior. This goes beyond schema descriptions.

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 returns 'real reporting channels for digital incidents' with specific examples (DNSC 1911, Romanian Police, etc.). It distinguishes itself from siblings like compass_find_playbook (which searches playbooks) and compass_get_content (retrieves content) by focusing on reporting channels.

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 explicit guidance on lang values: ro/en/hu produce Romania channels, pl produces Poland channels. Also explains effect of slug (with slug: only that situation's channels; without: all deduplicated). Lacks explicit 'when not to use' but implicitly differentiates from siblings.

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