Insight Digger MCP

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds context: it discloses authentication requirements ('Requires Authentication'), caching behavior ('Auto-Cached'), and workflow dependencies. It doesn't cover all potential behavioral traits (e.g., error handling or rate limits), but it provides significant operational context beyond the basic action.

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 appropriately sized but not optimally structured. It uses emojis and formatting (e.g., '🔒', '⚠️') for emphasis, which adds visual clutter. The information is front-loaded with key points, but the sentences could be more streamlined; for example, the authentication warning is repeated in different forms. It earns its place but lacks polish.

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 the complexity (2 required parameters, nested objects, no output schema, and no annotations), the description is fairly complete. It covers purpose, usage, dependencies, and behavioral aspects like authentication and caching. However, it doesn't explain the return values or potential errors, which would enhance completeness for a tool with no output schema.

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 description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'markdownConfig' is from 'create_configuration' and 'sourceStructure' from 'analyze_source_structure,' and notes that parameters are typically auto-cached and not manually provided. This clarifies the semantics and usage of the parameters, though it doesn't detail their internal structure or validation rules.

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: 'Create a dashboard from config, source structure, and API settings.' It specifies the verb ('Create') and resource ('dashboard'), and distinguishes it from siblings like 'create_configuration' by mentioning it's a 'granular step in the analysis workflow.' However, it doesn't fully differentiate from all siblings (e.g., 'generate_config' or 'generate_strategy'), keeping it from a perfect score.

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 explicit usage guidelines: it states 'You typically don't need to provide any parameters for this tool' due to auto-caching, names the prerequisite tool 'setup_authentication' with a warning to authenticate first, and mentions dependencies on outputs from 'create_configuration' and 'analyze_source_structure.' This clearly defines when and how to use the tool versus alternatives.

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