AGR MCP Server

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

With no annotations provided, the description carries the full burden. It describes what the tool does (builds and runs queries) and provides an example, but doesn't disclose important behavioral traits like rate limits, authentication requirements, error handling, pagination behavior, or what happens with complex queries. The example helps but leaves operational details unspecified.

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 perfectly structured and concise. It starts with the core purpose, provides a detailed example that demonstrates multiple parameters in action, and ends with the supported operators list. Every sentence earns its place, with no wasted words or 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?

For a complex query-building tool with 6 parameters, nested objects, and no output schema, the description is adequate but incomplete. The example query helps, but without annotations or output schema, it doesn't cover important aspects like response format, error conditions, performance characteristics, or how results are structured. The description does what it can but leaves significant gaps given the tool's complexity.

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 100% schema description coverage, the schema already documents all 6 parameters thoroughly. The description adds value by providing a concrete example query that demonstrates how parameters work together and lists supported operators for the 'where' clause, but doesn't add significant semantic meaning beyond what the schema provides. The baseline of 3 is appropriate given the comprehensive schema documentation.

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 with specific verbs ('Build and run structured queries') and resources ('against AllianceMine using a JSON DSL'). It distinguishes from sibling tools like 'mine_natural_query' (which likely uses natural language) and 'mine_search' (which might be simpler search) by emphasizing the structured JSON DSL approach.

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 context for when to use this tool (for structured queries with JSON DSL) but doesn't explicitly state when NOT to use it or name specific alternatives. The example query and operator list give practical guidance, but there's no direct comparison to sibling tools like 'mine_natural_query' or 'mine_search'.

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